activesupport 8.0.3 → 8.1.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2cdf9736ba5b94841913f95e5e83f01cc82becad9006ed2d75e18f1cc117c43
-  data.tar.gz: 7f8f545780e7ecfece1bdd6af006e504d91e89ad019a1020cd43014a296e7def
+  metadata.gz: 961314ec0e1413ca082492acda67d57e19e5011d13725707c3b3d83cb3e88b6c
+  data.tar.gz: '0918a0dcb857f0621acf8c0034cc568efceddbaf92991da1d73ea1a3ae892f40'
 SHA512:
-  metadata.gz: b23ff4bae6aae8f2e154b478c8f36825d0179152a0591591c240ea2b8d6104dcad0b70598a9b42888ab41448a06bc6b69c4ca537c1e5edb386fa81408f25acde
-  data.tar.gz: 84fa236c5c86feff0ae2283888ca7266c5f5d9090474b099c2b9142c082e107062bea571d8197f0138a022d7db7fe08e02f3544ade6cd611de68c35b26b90e75
+  metadata.gz: d167935a467f95a7dd138a7498328e7f8bb5970ad79e33ea43267fe79d6a40f5515abc768f9aa995d15e8678638e34a4b1ce925797a216bc7b5b26ab8ea97be7
+  data.tar.gz: 01edbccd59380207d979f9a504619a862c475217eecd9c8972af5868e4f870e405a511babb6925a7723038c7da395a94ecbaf1a3e3e8fb1f4f07dd7300d0321a

data/CHANGELOG.md

@@ -1,309 +1,371 @@
-## Rails 8.0.3 (September 22, 2025) ##
+## Rails 8.1.0.beta1 (September 04, 2025) ##
 
-*   `ActiveSupport::FileUpdateChecker` does not depend on `Time.now` to prevent unnecessary reloads with time travel test helpers
+*   Add `ActiveSupport::Cache::Store#namespace=` and `#namespace`.
 
-    *Jan Grodowski*
+    Can be used as an alternative to `Store#clear` in some situations such as parallel
+    testing.
 
-*   Fix `ActiveSupport::BroadcastLogger` from executing a block argument for each logger (tagged, info, etc.).
-
-    *Jared Armstrong*
-
-*   Make `ActiveSupport::Logger` `#freeze`-friendly.
-
-    *Joshua Young*
+    *Nick Schwaderer*
 
-*   Fix `ActiveSupport::HashWithIndifferentAccess#transform_keys!` removing defaults.
+*   Create `parallel_worker_id` helper for running parallel tests. This allows users to
+    know which worker they are currently running in.
 
-    *Hartley McGuire*
+    *Nick Schwaderer*
 
-*   Fix `ActiveSupport::HashWithIndifferentAccess#tranform_keys!` to handle collisions.
+*   Make the cache of `ActiveSupport::Cache::Strategy::LocalCache::Middleware` updatable.
 
-    If the transformation would result in a key equal to another not yet transformed one,
-    it would result in keys being lost.
+    If the cache client at `Rails.cache` of a booted application changes, the corresponding
+    mounted middleware needs to update in order for request-local caches to be setup properly.
+    Otherwise, redundant cache operations will erroneously hit the datastore.
 
-    Before:
+    *Gannon McGibbon*
 
-    ```ruby
-    >> {a: 1, b: 2}.with_indifferent_access.transform_keys!(&:succ)
-    => {"c" => 1}
-    ```
+*   Add `assert_events_reported` test helper for `ActiveSupport::EventReporter`.
 
-    After:
+    This new assertion allows testing multiple events in a single block, regardless of order:
 
     ```ruby
-    >> {a: 1, b: 2}.with_indifferent_access.transform_keys!(&:succ)
-    => {"c" => 1, "d" => 2}
+    assert_events_reported([
+      { name: "user.created", payload: { id: 123 } },
+      { name: "email.sent", payload: { to: "user@example.com" } }
+    ]) do
+      create_user_and_send_welcome_email
+    end
     ```
 
-    *Jason T Johnson*, *Jean Boussier*
-
-*   Fix `ActiveSupport::Cache::MemCacheStore#read_multi` to handle network errors.
-
-    This method specifically wasn't handling network errors like other codepaths.
+    *George Ma*
 
-    *Alessandro Dal Grande*
+*   Add `ActiveSupport::TimeZone#standard_name` method.
 
-*   Fix configuring `RedisCacheStore` with `raw: true`.
-
-    *fatkodima*
+    ``` ruby
+    zone = ActiveSupport::TimeZone['Hawaii']
+    # Old way
+    ActiveSupport::TimeZone::MAPPING[zone.name]
+    # New way
+    zone.standard_name # => 'Pacific/Honolulu'
+    ```
 
-*   Fix `Enumerable#sole` for infinite collections.
+    *Bogdan Gusiev*
 
-    *fatkodima*
+*   Add Structured Event Reporter, accessible via `Rails.event`.
 
+    The Event Reporter provides a unified interface for producing structured events in Rails
+    applications:
 
-## Rails 8.0.2.1 (August 13, 2025) ##
+    ```ruby
+    Rails.event.notify("user.signup", user_id: 123, email: "user@example.com")
+    ```
 
-*   No changes.
+    It supports adding tags to events:
 
+    ```ruby
+    Rails.event.tagged("graphql") do
+      # Event includes tags: { graphql: true }
+      Rails.event.notify("user.signup", user_id: 123, email: "user@example.com")
+    end
+    ```
 
-## Rails 8.0.2 (March 12, 2025) ##
+    As well as context:
+    ```ruby
+    # All events will contain context: {request_id: "abc123", shop_id: 456}
+    Rails.event.set_context(request_id: "abc123", shop_id: 456)
+    ```
 
-*   Fix setting `to_time_preserves_timezone` from `new_framework_defaults_8_0.rb`.
+    Events are emitted to subscribers. Applications register subscribers to
+    control how events are serialized and emitted. Subscribers must implement
+    an `#emit` method, which receives the event hash:
 
-    *fatkodima*
+    ```ruby
+    class LogSubscriber
+      def emit(event)
+        payload = event[:payload].map { |key, value| "#{key}=#{value}" }.join(" ")
+        source_location = event[:source_location]
+        log = "[#{event[:name]}] #{payload} at #{source_location[:filepath]}:#{source_location[:lineno]}"
+        Rails.logger.info(log)
+      end
+    end
+    ```
 
-*   Fix Active Support Cache `fetch_multi` when local store is active.
+    *Adrianna Chang*
 
-    `fetch_multi` now properly yield to the provided block for missing entries
-    that have been recorded as such in the local store.
+*   Make `ActiveSupport::Logger` `#freeze`-friendly.
 
-    *Jean Boussier*
+    *Joshua Young*
 
-*   Fix execution wrapping to report all exceptions, including `Exception`.
+*   Make `ActiveSupport::Gzip.compress` deterministic based on input.
 
-    If a more serious error like `SystemStackError` or `NoMemoryError` happens,
-    the error reporter should be able to report these kinds of exceptions.
+    `ActiveSupport::Gzip.compress` used to include a timestamp in the output,
+    causing consecutive calls with the same input data to have different output
+    if called during different seconds. It now always sets the timestamp to `0`
+    so that the output is identical for any given input.
 
-    *Gannon McGibbon*
+    *Rob Brackett*
 
-*   Fix `RedisCacheStore` and `MemCacheStore` to also handle connection pool related errors.
+*   Given an array of `Thread::Backtrace::Location` objects, the new method
+    `ActiveSupport::BacktraceCleaner#clean_locations` returns an array with the
+    clean ones:
 
-    These errors are rescued and reported to `Rails.error`.
+    ```ruby
+    clean_locations = backtrace_cleaner.clean_locations(caller_locations)
+    ```
 
-    *Jean Boussier*
+    Filters and silencers receive strings as usual. However, the `path`
+    attributes of the locations in the returned array are the original,
+    unfiltered ones, since locations are immutable.
 
-*   Fix `ActiveSupport::Cache#read_multi` to respect version expiry when using local cache.
+    *Xavier Noria*
 
-    *zzak*
+*   Improve `CurrentAttributes` and `ExecutionContext` state managment in test cases.
 
-*   Fix `ActiveSupport::MessageVerifier` and `ActiveSupport::MessageEncryptor` configuration of `on_rotation` callback.
+    Previously these two global state would be entirely cleared out whenever calling
+    into code that is wrapped by the Rails executor, typically Action Controller or
+    Active Job helpers:
 
     ```ruby
-    verifier.rotate(old_secret).on_rotation { ... }
+    test "#index works" do
+      CurrentUser.id = 42
+      get :index
+      CurrentUser.id == nil
+    end
     ```
 
-    Now both work as documented.
+    Now re-entering the executor properly save and restore that state.
 
     *Jean Boussier*
 
-*   Fix `ActiveSupport::MessageVerifier` to always be able to verify both URL-safe and URL-unsafe payloads.
-
-    This is to allow transitioning seemlessly from either configuration without immediately invalidating
-    all previously generated signed messages.
-
-    *Jean Boussier*, *Florent Beaurain*, *Ali Sepehri*
-
-*   Fix `cache.fetch` to honor the provided expiry when `:race_condition_ttl` is used.
-
-    ```ruby
-    cache.fetch("key", expires_in: 1.hour, race_condition_ttl: 5.second) do
-      "something"
-    end
-    ```
+*   The new method `ActiveSupport::BacktraceCleaner#first_clean_location`
+    returns the first clean location of the caller's call stack, or `nil`.
+    Locations are `Thread::Backtrace::Location` objects. Useful when you want to
+    report the application-level location where something happened as an object.
 
-    In the above example, the final cache entry would have a 10 seconds TTL instead
-    of the requested 1 hour.
+    *Xavier Noria*
 
-    *Dhia*
+*   FileUpdateChecker and EventedFileUpdateChecker ignore changes in Gem.path now.
 
-*   Better handle procs with splat arguments in `set_callback`.
+    *Ermolaev Andrey*, *zzak*
 
-    *Radamés Roriz*
+*   The new method `ActiveSupport::BacktraceCleaner#first_clean_frame` returns
+    the first clean frame of the caller's backtrace, or `nil`. Useful when you
+    want to report the application-level frame where something happened as a
+    string.
 
-*   Fix `String#mb_chars` to not mutate the receiver.
+    *Xavier Noria*
 
-    Previously it would call `force_encoding` on the receiver,
-    now it dups the receiver first.
+*   Always clear `CurrentAttributes` instances.
 
-    *Jean Boussier*
+    Previously `CurrentAttributes` instance would be reset at the end of requests.
+    Meaning its attributes would be re-initialized.
 
-*   Improve `ErrorSubscriber` to also mark error causes as reported.
+    This is problematic because it assume these objects don't hold any state
+    other than their declared attribute, which isn't always the case, and
+    can lead to state leak across request.
 
-    This avoid some cases of errors being reported twice, notably in views because of how
-    errors are wrapped in `ActionView::Template::Error`.
+    Now `CurrentAttributes` instances are abandoned at the end of a request,
+    and a new instance is created at the start of the next request.
 
-    *Jean Boussier*
+    *Jean Boussier*, *Janko Marohnić*
 
-*   Fix `Module#module_parent_name` to return the correct name after the module has been named.
+*   Add public API for `before_fork_hook` in parallel testing.
 
-    When called on an anonymous module, the return value wouldn't change after the module was given a name
-    later by being assigned to a constant.
+    Introduces a public API for calling the before fork hooks implemented by parallel testing.
 
     ```ruby
-    mod = Module.new
-    mod.module_parent_name # => "Object"
-    MyModule::Something = mod
-    mod.module_parent_name # => "MyModule"
+    parallelize_before_fork do
+        # perform an action before test processes are forked
+    end
     ```
 
-    *Jean Boussier*
+    *Eileen M. Uchitelle*
 
+*   Implement ability to skip creating parallel testing databases.
 
-## Rails 8.0.1 (December 13, 2024) ##
+    With parallel testing, Rails will create a database per process. If this isn't
+    desirable or you would like to implement databases handling on your own, you can
+    now turn off this default behavior.
 
-*   Fix a bug in `ERB::Util.tokenize` that causes incorrect tokenization when ERB tags are preceeded by multibyte characters.
+    To skip creating a database per process, you can change it via the
+    `parallelize` method:
 
-    *Martin Emde*
+    ```ruby
+    parallelize(workers: 10, parallelize_databases: false)
+    ```
 
-*   Restore the ability to decorate methods generated by `class_attribute`.
+    or via the application configuration:
 
-    It always has been complicated to use Module#prepend or an alias method chain
-    to decorate methods defined by `class_attribute`, but became even harder in 8.0.
+    ```ruby
+    config.active_support.parallelize_databases = false
+    ```
 
-    This capability is now supported for both reader and writer methods.
+    *Eileen M. Uchitelle*
 
-    *Jean Boussier*
+*   Allow to configure maximum cache key sizes
 
+    When the key exceeds the configured limit (250 bytes by default), it will be truncated and
+    the digest of the rest of the key appended to it.
 
-## Rails 8.0.0.1 (December 10, 2024) ##
+    Note that previously `ActiveSupport::Cache::RedisCacheStore` allowed up to 1kb cache keys before
+    truncation, which is now reduced to 250 bytes.
 
-*   No changes.
+    ```ruby
+    config.cache_store = :redis_cache_store, { max_key_size: 64 }
+    ```
 
+    *fatkodima*
 
-## Rails 8.0.0 (November 07, 2024) ##
+*   Use `UNLINK` command instead of `DEL` in `ActiveSupport::Cache::RedisCacheStore` for non-blocking deletion.
 
-*   No changes.
+    *Aron Roh*
 
+*   Add `Cache#read_counter` and `Cache#write_counter`
 
-## Rails 8.0.0.rc2 (October 30, 2024) ##
+    ```ruby
+    Rails.cache.write_counter("foo", 1)
+    Rails.cache.read_counter("foo") # => 1
+    Rails.cache.increment("foo")
+    Rails.cache.read_counter("foo") # => 2
+    ```
 
-*   No changes.
+    *Alex Ghiculescu*
 
+*   Introduce ActiveSupport::Testing::ErrorReporterAssertions#capture_error_reports
 
-## Rails 8.0.0.rc1 (October 19, 2024) ##
+    Captures all reported errors from within the block that match the given
+    error class.
 
-*   Remove deprecated support to passing an array of strings to `ActiveSupport::Deprecation#warn`.
+    ```ruby
+    reports = capture_error_reports(IOError) do
+      Rails.error.report(IOError.new("Oops"))
+      Rails.error.report(IOError.new("Oh no"))
+      Rails.error.report(StandardError.new)
+    end
 
-    *Rafael Mendonça França*
+    assert_equal 2, reports.size
+    assert_equal "Oops", reports.first.error.message
+    assert_equal "Oh no", reports.last.error.message
+    ```
 
-*   Remove deprecated support to setting `attr_internal_naming_format` with a `@` prefix.
+    *Andrew Novoselac*
 
-    *Rafael Mendonça França*
+*   Introduce ActiveSupport::ErrorReporter#add_middleware
 
-*   Remove deprecated `ActiveSupport::ProxyObject`.
+    When reporting an error, the error context middleware will be called with the reported error
+    and base execution context. The stack may mutate the context hash. The mutated context will
+    then be passed to error subscribers. Middleware receives the same parameters as `ErrorReporter#report`.
 
-    *Rafael Mendonça França*
+    *Andrew Novoselac*, *Sam Schmidt*
 
-*   Don't execute i18n watcher on boot. It shouldn't catch any file changes initially,
-    and unnecessarily slows down boot of applications with lots of translations.
+*   Change execution wrapping to report all exceptions, including `Exception`.
 
-    *Gannon McGibbon*, *David Stosik*
+    If a more serious error like `SystemStackError` or `NoMemoryError` happens,
+    the error reporter should be able to report these kinds of exceptions.
 
-*   Fix `ActiveSupport::HashWithIndifferentAccess#stringify_keys` to stringify all keys not just symbols.
+    *Gannon McGibbon*
 
-    Previously:
+*   `ActiveSupport::Testing::Parallelization.before_fork_hook` allows declaration of callbacks that
+    are invoked immediately before forking test workers.
 
-    ```ruby
-    { 1 => 2 }.with_indifferent_access.stringify_keys[1] # => 2
-    ```
+    *Mike Dalessio*
 
-    After this change:
+*   Allow the `#freeze_time` testing helper to accept a date or time argument.
 
     ```ruby
-    { 1 => 2 }.with_indifferent_access.stringify_keys["1"] # => 2
+    Time.current # => Sun, 09 Jul 2024 15:34:49 EST -05:00
+    freeze_time Time.current + 1.day
+    sleep 1
+    Time.current # => Mon, 10 Jul 2024 15:34:49 EST -05:00
     ```
 
-    This change can be seen as a bug fix, but since it behaved like this for a very long time, we're deciding
-    to not backport the fix and to make the change in a major release.
-
-    *Jean Boussier*
+    *Joshua Young*
 
-## Rails 8.0.0.beta1 (September 26, 2024) ##
+*   `ActiveSupport::JSON` now accepts options
 
-*   Include options when instrumenting `ActiveSupport::Cache::Store#delete` and `ActiveSupport::Cache::Store#delete_multi`.
+    It is now possible to pass options to `ActiveSupport::JSON`:
+    ```ruby
+    ActiveSupport::JSON.decode('{"key": "value"}', symbolize_names: true) # => { key: "value" }
+    ```
 
-    *Adam Renberg Tamm*
+    *matthaigh27*
 
-*   Print test names when running `rails test -v` for parallel tests.
+*   `ActiveSupport::Testing::NotificationAssertions`'s `assert_notification` now matches against payload subsets by default.
 
-    *John Hawthorn*, *Abeid Ahmed*
+    Previously the following assertion would fail due to excess key vals in the notification payload. Now with payload subset matching, it will pass.
 
-*   Deprecate `Benchmark.ms` core extension.
+    ```ruby
+    assert_notification("post.submitted", title: "Cool Post") do
+      ActiveSupport::Notifications.instrument("post.submitted", title: "Cool Post", body: "Cool Body")
+    end
+    ```
 
-    The `benchmark` gem will become bundled in Ruby 3.5
+    Additionally, you can now persist a matched notification for more customized assertions.
 
-    *Earlopain*
+    ```ruby
+    notification = assert_notification("post.submitted", title: "Cool Post") do
+      ActiveSupport::Notifications.instrument("post.submitted", title: "Cool Post", body: Body.new("Cool Body"))
+    end
 
-*   `ActiveSupport::TimeWithZone#inspect` now uses ISO 8601 style time like `Time#inspect`
+    assert_instance_of(Body, notification.payload[:body])
+    ```
 
-    *John Hawthorn*
+    *Nicholas La Roux*
 
-*   `ActiveSupport::ErrorReporter#report` now assigns a backtrace to unraised exceptions.
+*   Deprecate `String#mb_chars` and `ActiveSupport::Multibyte::Chars`.
 
-    Previously reporting an un-raised exception would result in an error report without
-    a backtrace. Now it automatically generates one.
+    These APIs are a relic of the Ruby 1.8 days when Ruby strings weren't encoding
+    aware. There is no legitimate reasons to need these APIs today.
 
     *Jean Boussier*
 
-*   Add `escape_html_entities` option to `ActiveSupport::JSON.encode`.
+*   Deprecate `ActiveSupport::Configurable`
 
-    This allows for overriding the global configuration found at
-    `ActiveSupport.escape_html_entities_in_json` for specific calls to `to_json`.
+    *Sean Doyle*
 
-    This should be usable from controllers in the following manner:
-    ```ruby
-    class MyController < ApplicationController
-      def index
-        render json: { hello: "world" }, escape_html_entities: false
-      end
-    end
-    ```
+*   `nil.to_query("key")` now returns `key`.
 
-    *Nigel Baillie*
+    Previously it would return `key=`, preventing round tripping with `Rack::Utils.parse_nested_query`.
 
-*   Raise when using key which can't respond to `#to_sym` in `EncryptedConfiguration`.
+    *Erol Fornoles*
 
-    As is the case when trying to use an Integer or Float as a key, which is unsupported.
+*   Avoid wrapping redis in a `ConnectionPool` when using `ActiveSupport::Cache::RedisCacheStore` if the `:redis`
+    option is already a `ConnectionPool`.
 
-    *zzak*
+    *Joshua Young*
 
-*   Deprecate addition and since between two `Time` and `ActiveSupport::TimeWithZone`.
+*   Alter `ERB::Util.tokenize` to return :PLAIN token with full input string when string doesn't contain ERB tags.
 
-    Previously adding time instances together such as `10.days.ago + 10.days.ago` or `10.days.ago.since(10.days.ago)` produced a nonsensical future date. This behavior is deprecated and will be removed in Rails 8.1.
+    *Martin Emde*
 
-    *Nick Schwaderer*
+*   Fix a bug in `ERB::Util.tokenize` that causes incorrect tokenization when ERB tags are preceded by multibyte characters.
 
-*   Support rfc2822 format for Time#to_fs & Date#to_fs.
+    *Martin Emde*
 
-    *Akshay Birajdar*
+*   Add `ActiveSupport::Testing::NotificationAssertions` module to help with testing `ActiveSupport::Notifications`.
 
-*   Optimize load time for `Railtie#initialize_i18n`. Filter `I18n.load_path`s passed to the file watcher to only those
-    under `Rails.root`. Previously the watcher would grab all available locales, including those in gems
-    which do not require a watcher because they won't change.
+    *Nicholas La Roux*, *Yishu See*, *Sean Doyle*
 
-    *Nick Schwaderer*
+*   `ActiveSupport::CurrentAttributes#attributes` now will return a new hash object on each call.
 
-*   Add a `filter` option to `in_order_of` to prioritize certain values in the sorting without filtering the results
-    by these values.
+    Previously, the same hash object was returned each time that method was called.
 
-    *Igor Depolli*
+    *fatkodima*
 
-*   Improve error message when using `assert_difference` or `assert_changes` with a
-    proc by printing the proc's source code (MRI only).
+*   `ActiveSupport::JSON.encode` supports CIDR notation.
 
-    *Richard Böhme*, *Jean Boussier*
+    Previously:
 
-*   Add a new configuration value `:zone` for `ActiveSupport.to_time_preserves_timezone` and rename the previous `true` value to `:offset`. The new default value is `:zone`.
+    ```ruby
+    ActiveSupport::JSON.encode(IPAddr.new("172.16.0.0/24")) # => "\"172.16.0.0\""
+    ```
 
-    *Jason Kim*, *John Hawthorn*
+    After this change:
 
-*   Align instrumentation `payload[:key]` in ActiveSupport::Cache to follow the same pattern, with namespaced and normalized keys.
+    ```ruby
+    ActiveSupport::JSON.encode(IPAddr.new("172.16.0.0/24")) # => "\"172.16.0.0/24\""
+    ```
 
-    *Frederik Erbs Spang Thomsen*
+    *Taketo Takashima*
 
-*   Fix `travel_to` to set usec 0 when `with_usec` is `false` and the given argument String or DateTime.
+*   Make `ActiveSupport::FileUpdateChecker` faster when checking many file-extensions.
 
-    *mopp*
+    *Jonathan del Strother*
 
-Please check [7-2-stable](https://github.com/rails/rails/blob/7-2-stable/activesupport/CHANGELOG.md) for previous changes.
+Please check [8-0-stable](https://github.com/rails/rails/blob/8-0-stable/activesupport/CHANGELOG.md) for previous changes.

data/lib/active_support/backtrace_cleaner.rb

@@ -56,6 +56,18 @@ module ActiveSupport
     end
     alias :filter :clean
 
+    # Given an array of Thread::Backtrace::Location objects, returns an array
+    # with the clean ones:
+    #
+    #     clean_locations = backtrace_cleaner.clean_locations(caller_locations)
+    #
+    # Filters and silencers receive strings as usual. However, the +path+
+    # attributes of the locations in the returned array are the original,
+    # unfiltered ones, since locations are immutable.
+    def clean_locations(locations, kind = :silent)
+      locations.select { |location| clean_frame(location, kind) }
+    end
+
     # Returns the frame with all filters applied.
     # returns +nil+ if the frame was silenced.
     def clean_frame(frame, kind = :silent)
@@ -74,6 +86,65 @@ module ActiveSupport
       end
     end
 
+    # Thread.each_caller_location does not accept a start in Ruby < 3.4.
+    if Thread.method(:each_caller_location).arity == 0
+      # Returns the first clean frame of the caller's backtrace, or +nil+.
+      #
+      # Frames are strings.
+      def first_clean_frame(kind = :silent)
+        caller_location_skipped = false
+
+        Thread.each_caller_location do |location|
+          unless caller_location_skipped
+            caller_location_skipped = true
+            next
+          end
+
+          frame = clean_frame(location, kind)
+          return frame if frame
+        end
+      end
+
+      # Returns the first clean location of the caller's call stack, or +nil+.
+      #
+      # Locations are Thread::Backtrace::Location objects. Since they are
+      # immutable, their +path+ attributes are the original ones, but filters
+      # are applied internally so silencers can still rely on them.
+      def first_clean_location(kind = :silent)
+        caller_location_skipped = false
+
+        Thread.each_caller_location do |location|
+          unless caller_location_skipped
+            caller_location_skipped = true
+            next
+          end
+
+          return location if clean_frame(location, kind)
+        end
+      end
+    else
+      # Returns the first clean frame of the caller's backtrace, or +nil+.
+      #
+      # Frames are strings.
+      def first_clean_frame(kind = :silent)
+        Thread.each_caller_location(2) do |location|
+          frame = clean_frame(location, kind)
+          return frame if frame
+        end
+      end
+
+      # Returns the first clean location of the caller's call stack, or +nil+.
+      #
+      # Locations are Thread::Backtrace::Location objects. Since they are
+      # immutable, their +path+ attributes are the original ones, but filters
+      # are applied internally so silencers can still rely on them.
+      def first_clean_location(kind = :silent)
+        Thread.each_caller_location(2) do |location|
+          return location if clean_frame(location, kind)
+        end
+      end
+    end
+
     # Adds a filter from the block provided. Each line in the backtrace will be
     # mapped against this filter.
     #