activesupport 1.2.4 → 8.1.2

data/lib/active_support/backtrace_cleaner.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  # = Backtrace Cleaner
+  #
+  # Backtraces often include many lines that are not relevant for the context
+  # under review. This makes it hard to find the signal amongst the backtrace
+  # noise, and adds debugging time. With a BacktraceCleaner, filters and
+  # silencers are used to remove the noisy lines, so that only the most relevant
+  # lines remain.
+  #
+  # Filters are used to modify lines of data, while silencers are used to remove
+  # lines entirely. The typical filter use case is to remove lengthy path
+  # information from the start of each line, and view file paths relevant to the
+  # app directory instead of the file system root. The typical silencer use case
+  # is to exclude the output of a noisy library from the backtrace, so that you
+  # can focus on the rest.
+  #
+  #   bc = ActiveSupport::BacktraceCleaner.new
+  #   root = "#{Rails.root}/"
+  #   bc.add_filter   { |line| line.delete_prefix(root) } # strip the Rails.root prefix
+  #   bc.add_silencer { |line| /puma|rubygems/.match?(line) } # skip any lines from puma or rubygems
+  #   bc.clean(exception.backtrace) # perform the cleanup
+  #
+  # To reconfigure an existing BacktraceCleaner (like the default one in \Rails)
+  # and show as much data as possible, you can always call
+  # BacktraceCleaner#remove_silencers!, which will restore the
+  # backtrace to a pristine state. If you need to reconfigure an existing
+  # BacktraceCleaner so that it does not filter or modify the paths of any lines
+  # of the backtrace, you can call BacktraceCleaner#remove_filters!
+  # These two methods will give you a completely untouched backtrace.
+  #
+  # Inspired by the Quiet Backtrace gem by thoughtbot.
+  class BacktraceCleaner
+    def initialize
+      @filters, @silencers = [], []
+      add_core_silencer
+      add_gem_filter
+      add_gem_silencer
+      add_stdlib_silencer
+    end
+
+    # Returns the backtrace after all filters and silencers have been run
+    # against it. Filters run first, then silencers.
+    def clean(backtrace, kind = :silent)
+      filtered = filter_backtrace(backtrace)
+
+      case kind
+      when :silent
+        silence(filtered)
+      when :noise
+        noise(filtered)
+      else
+        filtered
+      end
+    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)
+      frame = frame.to_s
+      @filters.each do |f|
+        frame = f.call(frame.to_s)
+      end
+
+      case kind
+      when :silent
+        frame unless @silencers.any? { |s| s.call(frame) }
+      when :noise
+        frame if @silencers.any? { |s| s.call(frame) }
+      else
+        frame
+      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.
+    #
+    #   # Will turn "/my/rails/root/app/models/person.rb" into "app/models/person.rb"
+    #   root = "#{Rails.root}/"
+    #   backtrace_cleaner.add_filter { |line| line.delete_prefix(root) }
+    def add_filter(&block)
+      @filters << block
+    end
+
+    # Adds a silencer from the block provided. If the silencer returns +true+
+    # for a given line, it will be excluded from the clean backtrace.
+    #
+    #   # Will reject all lines that include the word "puma", like "/gems/puma/server.rb" or "/app/my_puma_server/rb"
+    #   backtrace_cleaner.add_silencer { |line| /puma/.match?(line) }
+    def add_silencer(&block)
+      @silencers << block
+    end
+
+    # Removes all silencers, but leaves in the filters. Useful if your
+    # context of debugging suddenly expands as you suspect a bug in one of
+    # the libraries you use.
+    def remove_silencers!
+      @silencers = []
+    end
+
+    # Removes all filters, but leaves in the silencers. Useful if you suddenly
+    # need to see entire filepaths in the backtrace that you had already
+    # filtered out.
+    def remove_filters!
+      @filters = []
+    end
+
+    private
+      FORMATTED_GEMS_PATTERN = /\A[^\/]+ \([\w.]+\) /
+
+      def initialize_copy(_other)
+        @filters = @filters.dup
+        @silencers = @silencers.dup
+      end
+
+      def add_gem_filter
+        gems_paths = (Gem.path | [Gem.default_dir]).map { |p| Regexp.escape(p) }
+        return if gems_paths.empty?
+
+        gems_regexp = %r{\A(#{gems_paths.join('|')})/(bundler/)?gems/([^/]+)-([\w.]+)/(.*)}
+        gems_result = '\3 (\4) \5'
+        add_filter { |line| line.sub(gems_regexp, gems_result) }
+      end
+
+      def add_core_silencer
+        add_silencer { |line| line.include?("<internal:") }
+      end
+
+      def add_gem_silencer
+        add_silencer { |line| FORMATTED_GEMS_PATTERN.match?(line) }
+      end
+
+      def add_stdlib_silencer
+        add_silencer { |line| line.start_with?(RbConfig::CONFIG["rubylibdir"]) }
+      end
+
+      def filter_backtrace(backtrace)
+        @filters.each do |f|
+          backtrace = backtrace.map { |line| f.call(line.to_s) }
+        end
+
+        backtrace
+      end
+
+      def silence(backtrace)
+        @silencers.each do |s|
+          backtrace = backtrace.reject { |line| s.call(line.to_s) }
+        end
+
+        backtrace
+      end
+
+      def noise(backtrace)
+        backtrace.select do |line|
+          @silencers.any? do |s|
+            s.call(line.to_s)
+          end
+        end
+      end
+  end
+end

data/lib/active_support/benchmark.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module Benchmark # :nodoc:
+    # Benchmark realtime in the specified time unit. By default,
+    # the returned unit is in seconds.
+    #
+    #   ActiveSupport::Benchmark.realtime { sleep 0.1 }
+    #   # => 0.10007
+    #
+    #   ActiveSupport::Benchmark.realtime(:float_millisecond) { sleep 0.1 }
+    #   # => 100.07
+    #
+    # `unit` can be any of the values accepted by Ruby's `Process.clock_gettime`.
+    def self.realtime(unit = :float_second, &block)
+      time_start = Process.clock_gettime(Process::CLOCK_MONOTONIC, unit)
+      yield
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, unit) - time_start
+    end
+  end
+end

data/lib/active_support/benchmarkable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+
+module ActiveSupport
+  # = \Benchmarkable
+  module Benchmarkable
+    # Allows you to measure the execution time of a block in a template and
+    # records the result to the log. Wrap this block around expensive operations
+    # or possible bottlenecks to get a time reading for the operation. For
+    # example, let's say you thought your file processing method was taking too
+    # long; you could wrap it in a benchmark block.
+    #
+    #  <% benchmark 'Process data files' do %>
+    #    <%= expensive_files_operation %>
+    #  <% end %>
+    #
+    # That would add something like "Process data files (345.2ms)" to the log,
+    # which you can then use to compare timings when optimizing your code.
+    #
+    # You may give an optional logger level (<tt>:debug</tt>, <tt>:info</tt>,
+    # <tt>:warn</tt>, <tt>:error</tt>) as the <tt>:level</tt> option. The
+    # default logger level value is <tt>:info</tt>.
+    #
+    #  <% benchmark 'Low-level files', level: :debug do %>
+    #    <%= lowlevel_files_operation %>
+    #  <% end %>
+    #
+    # Finally, you can pass true as the third argument to silence all log
+    # activity (other than the timing information) from inside the block. This
+    # is great for boiling down a noisy block to just a single statement that
+    # produces one log line:
+    #
+    #  <% benchmark 'Process data files', level: :info, silence: true do %>
+    #    <%= expensive_and_chatty_files_operation %>
+    #  <% end %>
+    def benchmark(message = "Benchmarking", options = {}, &block)
+      if logger
+        options.assert_valid_keys(:level, :silence)
+        options[:level] ||= :info
+
+        result = nil
+        ms = ActiveSupport::Benchmark.realtime(:float_millisecond) do
+          result = options[:silence] ? logger.silence(&block) : yield
+        end
+        logger.public_send(options[:level], "%s (%.1fms)" % [ message, ms ])
+        result
+      else
+        yield
+      end
+    end
+  end
+end

data/lib/active_support/broadcast_logger.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  # = Active Support Broadcast Logger
+  #
+  # The Broadcast logger is a logger used to write messages to multiple IO. It is commonly used
+  # in development to display messages on STDOUT and also write them to a file (development.log).
+  # With the Broadcast logger, you can broadcast your logs to a unlimited number of sinks.
+  #
+  # The BroadcastLogger acts as a standard logger and all methods you are used to are available.
+  # However, all the methods on this logger will propagate and be delegated to the other loggers
+  # that are part of the broadcast.
+  #
+  # Broadcasting your logs.
+  #
+  #   stdout_logger = Logger.new(STDOUT)
+  #   file_logger   = Logger.new("development.log")
+  #   broadcast = BroadcastLogger.new(stdout_logger, file_logger)
+  #
+  #   broadcast.info("Hello world!") # Writes the log to STDOUT and the development.log file.
+  #
+  # Add a logger to the broadcast.
+  #
+  #   stdout_logger = Logger.new(STDOUT)
+  #   broadcast = BroadcastLogger.new(stdout_logger)
+  #   file_logger   = Logger.new("development.log")
+  #   broadcast.broadcast_to(file_logger)
+  #
+  #   broadcast.info("Hello world!") # Writes the log to STDOUT and the development.log file.
+  #
+  # Modifying the log level for all broadcasted loggers.
+  #
+  #   stdout_logger = Logger.new(STDOUT)
+  #   file_logger   = Logger.new("development.log")
+  #   broadcast = BroadcastLogger.new(stdout_logger, file_logger)
+  #
+  #   broadcast.level = Logger::FATAL # Modify the log level for the whole broadcast.
+  #
+  # Stop broadcasting log to a sink.
+  #
+  #   stdout_logger = Logger.new(STDOUT)
+  #   file_logger   = Logger.new("development.log")
+  #   broadcast = BroadcastLogger.new(stdout_logger, file_logger)
+  #   broadcast.info("Hello world!") # Writes the log to STDOUT and the development.log file.
+  #
+  #   broadcast.stop_broadcasting_to(file_logger)
+  #   broadcast.info("Hello world!") # Writes the log *only* to STDOUT.
+  #
+  # At least one sink has to be part of the broadcast. Otherwise, your logs will not
+  # be written anywhere. For instance:
+  #
+  #   broadcast = BroadcastLogger.new
+  #   broadcast.info("Hello world") # The log message will appear nowhere.
+  #
+  # If you are adding a custom logger with custom methods to the broadcast,
+  # the `BroadcastLogger` will proxy them and return the raw value, or an array
+  # of raw values, depending on how many loggers in the broadcasts responded to
+  # the method:
+  #
+  #   class MyLogger < ::Logger
+  #     def loggable?
+  #       true
+  #     end
+  #   end
+  #
+  #   logger = BroadcastLogger.new
+  #   logger.loggable? # => A NoMethodError exception is raised because no loggers in the broadcasts could respond.
+  #
+  #   logger.broadcast_to(MyLogger.new(STDOUT))
+  #   logger.loggable? # => true
+  #   logger.broadcast_to(MyLogger.new(STDOUT))
+  #   puts logger.broadcasts # => [MyLogger, MyLogger]
+  #   logger.loggable? # [true, true]
+  class BroadcastLogger
+    include ActiveSupport::LoggerSilence
+
+    # Returns all the logger that are part of this broadcast.
+    attr_reader :broadcasts
+    attr_accessor :progname
+
+    def initialize(*loggers)
+      @broadcasts = []
+      @progname = "Broadcast"
+
+      broadcast_to(*loggers)
+    end
+
+    # Add logger(s) to the broadcast.
+    #
+    #   broadcast_logger = ActiveSupport::BroadcastLogger.new
+    #   broadcast_logger.broadcast_to(Logger.new(STDOUT), Logger.new(STDERR))
+    def broadcast_to(*loggers)
+      @broadcasts.concat(loggers)
+    end
+
+    # Remove a logger from the broadcast. When a logger is removed, messages sent to
+    # the broadcast will no longer be written to its sink.
+    #
+    #   sink = Logger.new(STDOUT)
+    #   broadcast_logger = ActiveSupport::BroadcastLogger.new
+    #
+    #   broadcast_logger.stop_broadcasting_to(sink)
+    def stop_broadcasting_to(logger)
+      @broadcasts.delete(logger)
+    end
+
+    def local_level=(level)
+      @broadcasts.each do |logger|
+        logger.local_level = level if logger.respond_to?(:local_level=)
+      end
+    end
+
+    def local_level
+      loggers = @broadcasts.select { |logger| logger.respond_to?(:local_level) }
+
+      loggers.map do |logger|
+        logger.local_level
+      end.first
+    end
+
+    LOGGER_METHODS = %w[
+      << log add debug info warn error fatal unknown
+      level= sev_threshold= close
+      formatter formatter=
+    ] # :nodoc:
+    LOGGER_METHODS.each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(...)
+          dispatch(:#{method}, ...)
+        end
+      RUBY
+    end
+
+    # Returns the lowest level of all the loggers in the broadcast.
+    def level
+      @broadcasts.map(&:level).min
+    end
+
+    # True if the log level allows entries with severity +Logger::DEBUG+ to be written
+    # to at least one broadcast. False otherwise.
+    def debug?
+      @broadcasts.any? { |logger| logger.debug? }
+    end
+
+    # Sets the log level to +Logger::DEBUG+ for the whole broadcast.
+    def debug!
+      dispatch(:debug!)
+    end
+
+    # True if the log level allows entries with severity +Logger::INFO+ to be written
+    # to at least one broadcast. False otherwise.
+    def info?
+      @broadcasts.any? { |logger| logger.info? }
+    end
+
+    # Sets the log level to +Logger::INFO+ for the whole broadcast.
+    def info!
+      dispatch(:info!)
+    end
+
+    # True if the log level allows entries with severity +Logger::WARN+ to be written
+    # to at least one broadcast. False otherwise.
+    def warn?
+      @broadcasts.any? { |logger| logger.warn? }
+    end
+
+    # Sets the log level to +Logger::WARN+ for the whole broadcast.
+    def warn!
+      dispatch(:warn!)
+    end
+
+    # True if the log level allows entries with severity +Logger::ERROR+ to be written
+    # to at least one broadcast. False otherwise.
+    def error?
+      @broadcasts.any? { |logger| logger.error? }
+    end
+
+    # Sets the log level to +Logger::ERROR+ for the whole broadcast.
+    def error!
+      dispatch(:error!)
+    end
+
+    # True if the log level allows entries with severity +Logger::FATAL+ to be written
+    # to at least one broadcast. False otherwise.
+    def fatal?
+      @broadcasts.any? { |logger| logger.fatal? }
+    end
+
+    # Sets the log level to +Logger::FATAL+ for the whole broadcast.
+    def fatal!
+      dispatch(:fatal!)
+    end
+
+    def initialize_copy(other)
+      @broadcasts = []
+      @progname = other.progname.dup
+
+      broadcast_to(*other.broadcasts.map(&:dup))
+    end
+
+    private
+      def dispatch(method, *args, **kwargs, &block)
+        if block_given?
+          # Maintain semantics that the first logger yields the block
+          # as normal, but subsequent loggers won't re-execute the block.
+          # Instead, the initial result is immediately returned.
+          called, result = false, nil
+          block = proc { |*args, **kwargs|
+            if called then result
+            else
+              called = true
+              result = yield(*args, **kwargs)
+            end
+          }
+        end
+
+        @broadcasts.map { |logger|
+          logger.send(method, *args, **kwargs, &block)
+        }.first
+      end
+
+      def method_missing(name, ...)
+        loggers = @broadcasts.select { |logger| logger.respond_to?(name) }
+
+        if loggers.none?
+          super
+        elsif loggers.one?
+          loggers.first.send(name, ...)
+        else
+          loggers.map { |logger| logger.send(name, ...) }
+        end
+      end
+
+      def respond_to_missing?(method, include_all)
+        @broadcasts.any? { |logger| logger.respond_to?(method, include_all) }
+      end
+  end
+end

data/lib/active_support/builder.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+begin
+  require "builder"
+rescue LoadError => e
+  warn "You don't have builder installed in your application. Please add it to your Gemfile and run bundle install"
+  raise e
+end