activesupport 1.2.4 → 8.1.2

data/lib/active_support/rescuable.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/string/inflections"
+
+module ActiveSupport
+  # = Active Support \Rescuable
+  #
+  # Rescuable module adds support for easier exception handling.
+  module Rescuable
+    extend Concern
+
+    included do
+      class_attribute :rescue_handlers, default: []
+    end
+
+    module ClassMethods
+      # Registers exception classes with a handler to be called by <tt>rescue_with_handler</tt>.
+      #
+      # <tt>rescue_from</tt> receives a series of exception classes or class
+      # names, and an exception handler specified by a trailing <tt>:with</tt>
+      # option containing the name of a method or a Proc object. Alternatively, a block
+      # can be given as the handler.
+      #
+      # Handlers that take one argument will be called with the exception, so
+      # that the exception can be inspected when dealing with it.
+      #
+      # Handlers are inherited. They are searched from right to left, from
+      # bottom to top, and up the hierarchy. The handler of the first class for
+      # which <tt>exception.is_a?(klass)</tt> holds true is the one invoked, if
+      # any.
+      #
+      #   class ApplicationController < ActionController::Base
+      #     rescue_from User::NotAuthorized, with: :deny_access
+      #     rescue_from ActiveRecord::RecordInvalid, with: :show_record_errors
+      #
+      #     rescue_from "MyApp::BaseError" do |exception|
+      #       redirect_to root_url, alert: exception.message
+      #     end
+      #
+      #     private
+      #       def deny_access
+      #         head :forbidden
+      #       end
+      #
+      #       def show_record_errors(exception)
+      #         redirect_back_or_to root_url, alert: exception.record.errors.full_messages.to_sentence
+      #       end
+      #   end
+      #
+      # Exceptions raised inside exception handlers are not propagated up.
+      def rescue_from(*klasses, with: nil, &block)
+        unless with
+          if block_given?
+            with = block
+          else
+            raise ArgumentError, "Need a handler. Pass the with: keyword argument or provide a block."
+          end
+        end
+
+        klasses.each do |klass|
+          key = if klass.is_a?(Module) && klass.respond_to?(:===)
+            klass.name
+          elsif klass.is_a?(String)
+            klass
+          else
+            raise ArgumentError, "#{klass.inspect} must be an Exception class or a String referencing an Exception class"
+          end
+
+          # Put the new handler at the end because the list is read in reverse.
+          self.rescue_handlers += [[key, with]]
+        end
+      end
+
+      # Matches an exception to a handler based on the exception class.
+      #
+      # If no handler matches the exception, check for a handler matching the
+      # (optional) +exception.cause+. If no handler matches the exception or its
+      # cause, this returns +nil+, so you can deal with unhandled exceptions.
+      # Be sure to re-raise unhandled exceptions if this is what you expect.
+      #
+      #     begin
+      #       # ...
+      #     rescue => exception
+      #       rescue_with_handler(exception) || raise
+      #     end
+      #
+      # Returns the exception if it was handled and +nil+ if it was not.
+      def rescue_with_handler(exception, object: self, visited_exceptions: [])
+        visited_exceptions << exception
+
+        if handler = handler_for_rescue(exception, object: object)
+          handler.call exception
+          exception
+        elsif exception
+          if visited_exceptions.include?(exception.cause)
+            nil
+          else
+            rescue_with_handler(exception.cause, object: object, visited_exceptions: visited_exceptions)
+          end
+        end
+      end
+
+      def handler_for_rescue(exception, object: self) # :nodoc:
+        case rescuer = find_rescue_handler(exception)
+        when Symbol
+          method = object.method(rescuer)
+          if method.arity == 0
+            -> e { method.call }
+          else
+            method
+          end
+        when Proc
+          if rescuer.arity == 0
+            -> e { object.instance_exec(&rescuer) }
+          else
+            -> e { object.instance_exec(e, &rescuer) }
+          end
+        end
+      end
+
+      private
+        def find_rescue_handler(exception)
+          if exception
+            # Handlers are in order of declaration but the most recently declared
+            # is the highest priority match, so we search for matching handlers
+            # in reverse.
+            _, handler = rescue_handlers.reverse_each.detect do |class_or_name, _|
+              if klass = constantize_rescue_handler_class(class_or_name)
+                klass === exception
+              end
+            end
+
+            handler
+          end
+        end
+
+        def constantize_rescue_handler_class(class_or_name)
+          case class_or_name
+          when String, Symbol
+            begin
+              # Try a lexical lookup first since we support
+              #
+              #     class Super
+              #       rescue_from 'Error', with: …
+              #     end
+              #
+              #     class Sub
+              #       class Error < StandardError; end
+              #     end
+              #
+              # so an Error raised in Sub will hit the 'Error' handler.
+              const_get class_or_name
+            rescue NameError
+              class_or_name.safe_constantize
+            end
+          else
+            class_or_name
+          end
+        end
+    end
+
+    # Delegates to the class method, but uses the instance as the subject for
+    # rescue_from handlers (method calls, +instance_exec+ blocks).
+    def rescue_with_handler(exception)
+      self.class.rescue_with_handler exception, object: self
+    end
+
+    # Internal handler lookup. Delegates to class method. Some libraries call
+    # this directly, so keeping it around for compatibility.
+    def handler_for_rescue(exception) # :nodoc:
+      self.class.handler_for_rescue exception, object: self
+    end
+  end
+end

data/lib/active_support/secure_compare_rotator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_support/security_utils"
+require "active_support/messages/rotator"
+
+module ActiveSupport
+  # = Secure Compare Rotator
+  #
+  # The ActiveSupport::SecureCompareRotator is a wrapper around ActiveSupport::SecurityUtils.secure_compare
+  # and allows you to rotate a previously defined value to a new one.
+  #
+  # It can be used as follow:
+  #
+  #   rotator = ActiveSupport::SecureCompareRotator.new('new_production_value')
+  #   rotator.rotate('previous_production_value')
+  #   rotator.secure_compare!('previous_production_value')
+  #
+  # One real use case example would be to rotate a basic auth credentials:
+  #
+  #   class MyController < ApplicationController
+  #     def authenticate_request
+  #       rotator = ActiveSupport::SecureCompareRotator.new('new_password')
+  #       rotator.rotate('old_password')
+  #
+  #       authenticate_or_request_with_http_basic do |username, password|
+  #         rotator.secure_compare!(password)
+  #       rescue ActiveSupport::SecureCompareRotator::InvalidMatch
+  #         false
+  #       end
+  #     end
+  #   end
+  class SecureCompareRotator
+    include SecurityUtils
+
+    InvalidMatch = Class.new(StandardError)
+
+    def initialize(value, on_rotation: nil)
+      @value = value
+      @rotate_values = []
+      @on_rotation = on_rotation
+    end
+
+    def rotate(previous_value)
+      @rotate_values << previous_value
+    end
+
+    def secure_compare!(other_value, on_rotation: @on_rotation)
+      if secure_compare(@value, other_value)
+        true
+      elsif @rotate_values.any? { |value| secure_compare(value, other_value) }
+        on_rotation&.call
+        true
+      else
+        raise InvalidMatch
+      end
+    end
+  end
+end

data/lib/active_support/security_utils.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module SecurityUtils
+    # Constant time string comparison, for fixed length strings.
+    #
+    # The values compared should be of fixed length, such as strings
+    # that have already been processed by HMAC. Raises in case of length mismatch.
+
+    if defined?(OpenSSL.fixed_length_secure_compare)
+      def fixed_length_secure_compare(a, b)
+        OpenSSL.fixed_length_secure_compare(a, b)
+      end
+    else
+      def fixed_length_secure_compare(a, b)
+        raise ArgumentError, "string length mismatch." unless a.bytesize == b.bytesize
+
+        l = a.unpack "C#{a.bytesize}"
+
+        res = 0
+        b.each_byte { |byte| res |= byte ^ l.shift }
+        res == 0
+      end
+    end
+    module_function :fixed_length_secure_compare
+
+    # Secure string comparison for strings of variable length.
+    #
+    # While a timing attack would not be able to discern the content of
+    # a secret compared via secure_compare, it is possible to determine
+    # the secret length. This should be considered when using secure_compare
+    # to compare weak, short secrets to user input.
+    def secure_compare(a, b)
+      a.bytesize == b.bytesize && fixed_length_secure_compare(a, b)
+    end
+    module_function :secure_compare
+  end
+end

data/lib/active_support/string_inquirer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  # = \String Inquirer
+  #
+  # Wrapping a string in this class gives you a prettier way to test
+  # for equality. The value returned by <tt>Rails.env</tt> is wrapped
+  # in a StringInquirer object, so instead of calling this:
+  #
+  #   Rails.env == 'production'
+  #
+  # you can call this:
+  #
+  #   Rails.env.production?
+  #
+  # == Instantiating a new \StringInquirer
+  #
+  #   vehicle = ActiveSupport::StringInquirer.new('car')
+  #   vehicle.car?   # => true
+  #   vehicle.bike?  # => false
+  class StringInquirer < String
+    private
+      def respond_to_missing?(method_name, include_private = false)
+        method_name.end_with?("?") || super
+      end
+
+      def method_missing(method_name, ...)
+        if method_name.end_with?("?")
+          self == method_name[0..-2]
+        else
+          super
+        end
+      end
+  end
+end

data/lib/active_support/structured_event_subscriber.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "active_support/subscriber"
+
+module ActiveSupport
+  # = Active Support Structured Event \Subscriber
+  #
+  # +ActiveSupport::StructuredEventSubscriber+ consumes ActiveSupport::Notifications
+  # in order to emit structured events via +Rails.event+.
+  #
+  # An example would be the Action Controller structured event subscriber, responsible for
+  # emitting request processing events:
+  #
+  #   module ActionController
+  #     class StructuredEventSubscriber < ActiveSupport::StructuredEventSubscriber
+  #       attach_to :action_controller
+  #
+  #       def start_processing(event)
+  #         emit_event("controller.request_started",
+  #           controller: event.payload[:controller],
+  #           action: event.payload[:action],
+  #           format: event.payload[:format]
+  #         )
+  #       end
+  #     end
+  #   end
+  #
+  # After configured, whenever a <tt>"start_processing.action_controller"</tt> notification is published,
+  # it will properly dispatch the event (+ActiveSupport::Notifications::Event+) to the +start_processing+ method.
+  # The subscriber can then emit a structured event via the +emit_event+ method.
+  class StructuredEventSubscriber < Subscriber
+    class_attribute :debug_methods, instance_accessor: false, default: [] # :nodoc:
+
+    DEBUG_CHECK = proc { !ActiveSupport.event_reporter.debug_mode? }
+
+    class << self
+      def attach_to(...) # :nodoc:
+        result = super
+        set_silenced_events
+        result
+      end
+
+      private
+        def set_silenced_events
+          if subscriber
+            subscriber.silenced_events = debug_methods.to_h { |method| ["#{method}.#{namespace}", DEBUG_CHECK] }
+          end
+        end
+
+        def debug_only(method)
+          self.debug_methods << method
+          set_silenced_events
+        end
+    end
+
+    def initialize
+      super
+      @silenced_events = {}
+    end
+
+    def silenced?(event)
+      ActiveSupport.event_reporter.subscribers.none? || @silenced_events[event]&.call
+    end
+
+    attr_writer :silenced_events # :nodoc:
+
+    # Emit a structured event via Rails.event.notify.
+    #
+    # ==== Arguments
+    #
+    # * +name+ - The event name as a string or symbol
+    # * +payload+ - The event payload as a hash or object
+    # * +caller_depth+ - Stack depth for source location (default: 1)
+    # * +kwargs+ - Additional payload data merged with the payload hash
+    def emit_event(name, payload = nil, caller_depth: 1, **kwargs)
+      ActiveSupport.event_reporter.notify(name, payload, caller_depth: caller_depth + 1, **kwargs)
+    rescue => e
+      handle_event_error(name, e)
+    end
+
+    # Like +emit_event+, but only emits when the event reporter is in debug mode
+    def emit_debug_event(name, payload = nil, caller_depth: 1, **kwargs)
+      ActiveSupport.event_reporter.debug(name, payload, caller_depth: caller_depth + 1, **kwargs)
+    rescue => e
+      handle_event_error(name, e)
+    end
+
+    def call(event)
+      super
+    rescue => e
+      handle_event_error(event.name, e)
+    end
+
+    private
+      def handle_event_error(name, error)
+        ActiveSupport.error_reporter.report(error, source: name)
+      end
+  end
+end

data/lib/active_support/subscriber.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module ActiveSupport
+  # = Active Support \Subscriber
+  #
+  # +ActiveSupport::Subscriber+ is an object set to consume
+  # ActiveSupport::Notifications. The subscriber dispatches notifications to
+  # a registered object based on its given namespace.
+  #
+  # An example would be an Active Record subscriber responsible for collecting
+  # statistics about queries:
+  #
+  #   module ActiveRecord
+  #     class StatsSubscriber < ActiveSupport::Subscriber
+  #       attach_to :active_record
+  #
+  #       def sql(event)
+  #         Statsd.timing("sql.#{event.payload[:name]}", event.duration)
+  #       end
+  #     end
+  #   end
+  #
+  # After configured, whenever a <tt>"sql.active_record"</tt> notification is
+  # published, it will properly dispatch the event
+  # (ActiveSupport::Notifications::Event) to the +sql+ method.
+  #
+  # We can detach a subscriber as well:
+  #
+  #   ActiveRecord::StatsSubscriber.detach_from(:active_record)
+  class Subscriber
+    class << self
+      # Attach the subscriber to a namespace.
+      def attach_to(namespace, subscriber = new, notifier = ActiveSupport::Notifications, inherit_all: false)
+        @namespace  = namespace
+        @subscriber = subscriber
+        @notifier   = notifier
+        @inherit_all = inherit_all
+
+        subscribers << subscriber
+
+        # Add event subscribers for all existing methods on the class.
+        fetch_public_methods(subscriber, inherit_all).each do |event|
+          add_event_subscriber(event)
+        end
+      end
+
+      # Detach the subscriber from a namespace.
+      def detach_from(namespace, notifier = ActiveSupport::Notifications)
+        @namespace  = namespace
+        @subscriber = find_attached_subscriber
+        @notifier   = notifier
+
+        return unless subscriber
+
+        subscribers.delete(subscriber)
+
+        # Remove event subscribers of all existing methods on the class.
+        fetch_public_methods(subscriber, true).each do |event|
+          remove_event_subscriber(event)
+        end
+
+        # Reset notifier so that event subscribers will not add for new methods added to the class.
+        @notifier = nil
+      end
+
+      # Adds event subscribers for all new methods added to the class.
+      def method_added(event)
+        super
+        # Only public methods are added as subscribers, and only if a notifier
+        # has been set up. This means that subscribers will only be set up for
+        # classes that call #attach_to.
+        if public_method_defined?(event) && notifier
+          add_event_subscriber(event)
+        end
+      end
+
+      def subscribers
+        @@subscribers ||= []
+      end
+
+      private
+        attr_reader :subscriber, :notifier, :namespace
+
+        def add_event_subscriber(event) # :doc:
+          return if invalid_event?(event)
+
+          pattern = prepare_pattern(event)
+
+          # Don't add multiple subscribers (e.g. if methods are redefined).
+          return if pattern_subscribed?(pattern)
+
+          subscriber.patterns[pattern] = notifier.subscribe(pattern, subscriber)
+        end
+
+        def remove_event_subscriber(event) # :doc:
+          return if invalid_event?(event)
+
+          pattern = prepare_pattern(event)
+
+          return unless pattern_subscribed?(pattern)
+
+          notifier.unsubscribe(subscriber.patterns[pattern])
+          subscriber.patterns.delete(pattern)
+        end
+
+        def find_attached_subscriber
+          subscribers.find { |attached_subscriber| attached_subscriber.instance_of?(self) }
+        end
+
+        def invalid_event?(event)
+          %i{ start finish }.include?(event.to_sym)
+        end
+
+        def prepare_pattern(event)
+          "#{event}.#{namespace}"
+        end
+
+        def pattern_subscribed?(pattern)
+          subscriber.patterns.key?(pattern)
+        end
+
+        def fetch_public_methods(subscriber, inherit_all)
+          subscriber.public_methods(inherit_all) - Subscriber.public_instance_methods(true)
+        end
+    end
+
+    attr_reader :patterns # :nodoc:
+
+    def initialize
+      @patterns  = {}
+      super
+    end
+
+    def call(event)
+      method = event.name[0, event.name.index(".")]
+      send(method, event)
+    end
+  end
+end

data/lib/active_support/syntax_error_proxy.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ActiveSupport
+  # This is a class for wrapping syntax errors.  The purpose of this class
+  # is to enhance the backtraces on SyntaxError exceptions to include the
+  # source location of the syntax error.  That way we can display the error
+  # source on error pages in development.
+  class SyntaxErrorProxy < DelegateClass(SyntaxError) # :nodoc:
+    def backtrace
+      parse_message_for_trace + super
+    end
+
+    class BacktraceLocation < Struct.new(:path, :lineno, :to_s) # :nodoc:
+      def spot(_)
+      end
+
+      def label
+      end
+
+      def base_label
+      end
+
+      def absolute_path
+        path
+      end
+    end
+
+    class BacktraceLocationProxy < DelegateClass(Thread::Backtrace::Location) # :nodoc:
+      def initialize(loc, ex)
+        super(loc)
+        @ex = ex
+      end
+
+      def spot(_)
+        super(@ex.__getobj__)
+      end
+    end
+
+    def backtrace_locations
+      return nil if super.nil?
+
+      parse_message_for_trace.map { |trace|
+        file, line = trace.match(/^(.+?):(\d+).*$/, &:captures) || trace
+        BacktraceLocation.new(file, line.to_i, trace)
+        # We have to wrap these backtrace locations because we need the
+        # spot information to come from the originating exception, not the
+        # proxy object that's generating these
+      } + super.map { |loc| BacktraceLocationProxy.new(loc, self) }
+    end
+
+    private
+      def parse_message_for_trace
+        if __getobj__.to_s.start_with?("(eval")
+          # If the exception is coming from a call to eval, we need to keep
+          # the path of the file in which eval was called to ensure we can
+          # return the right source fragment to show the location of the
+          # error
+          location = __getobj__.backtrace_locations[0]
+          ["#{location.path}:#{location.lineno}: #{__getobj__}"]
+        else
+          __getobj__.to_s.split("\n")
+        end
+      end
+  end
+end