activesupport 1.2.4 → 8.1.2

data/lib/active_support/encrypted_file.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "tempfile"
+require "active_support/message_encryptor"
+
+module ActiveSupport
+  class EncryptedFile
+    class MissingContentError < RuntimeError
+      def initialize(content_path)
+        super "Missing encrypted content file in #{content_path}."
+      end
+    end
+
+    class MissingKeyError < RuntimeError
+      def initialize(key_path:, env_key:)
+        super \
+          "Missing encryption key to decrypt file with. " +
+          "Ask your team for your master key and write it to #{key_path} or put it in the ENV['#{env_key}']."
+      end
+    end
+
+    class InvalidKeyLengthError < RuntimeError
+      def initialize
+        super "Encryption key must be exactly #{EncryptedFile.expected_key_length} characters."
+      end
+    end
+
+    CIPHER = "aes-128-gcm"
+
+    def self.generate_key
+      SecureRandom.hex(ActiveSupport::MessageEncryptor.key_len(CIPHER))
+    end
+
+    def self.expected_key_length # :nodoc:
+      @expected_key_length ||= generate_key.length
+    end
+
+
+    attr_reader :content_path, :key_path, :env_key, :raise_if_missing_key
+
+    def initialize(content_path:, key_path:, env_key:, raise_if_missing_key:)
+      @content_path = Pathname.new(content_path).yield_self { |path| path.symlink? ? path.realpath : path }
+      @key_path = Pathname.new(key_path)
+      @env_key, @raise_if_missing_key = env_key, raise_if_missing_key
+    end
+
+    # Returns the encryption key, first trying the environment variable
+    # specified by +env_key+, then trying the key file specified by +key_path+.
+    # If +raise_if_missing_key+ is true, raises MissingKeyError if the
+    # environment variable is not set and the key file does not exist.
+    def key
+      read_env_key || read_key_file || handle_missing_key
+    end
+
+    # Returns truthy if #key is truthy. Returns falsy otherwise. Unlike #key,
+    # does not raise MissingKeyError when +raise_if_missing_key+ is true.
+    def key?
+      read_env_key || read_key_file
+    end
+
+    # Reads the file and returns the decrypted content.
+    #
+    # Raises:
+    # - MissingKeyError if the key is missing and +raise_if_missing_key+ is true.
+    # - MissingContentError if the encrypted file does not exist or otherwise
+    #   if the key is missing.
+    # - ActiveSupport::MessageEncryptor::InvalidMessage if the content cannot be
+    #   decrypted or verified.
+    def read
+      if !key.nil? && content_path.exist?
+        decrypt content_path.binread.strip
+      else
+        raise MissingContentError, content_path
+      end
+    end
+
+    def write(contents)
+      IO.binwrite "#{content_path}.tmp", encrypt(contents)
+      FileUtils.mv "#{content_path}.tmp", content_path
+    end
+
+    def change(&block)
+      writing read, &block
+    end
+
+
+    private
+      def writing(contents)
+        Tempfile.create(["", "-" + content_path.basename.to_s.chomp(".enc")]) do |tmp_file|
+          tmp_path = Pathname.new(tmp_file)
+          tmp_path.binwrite contents
+
+          yield tmp_path
+
+          updated_contents = tmp_path.binread
+
+          write(updated_contents) if updated_contents != contents
+        end
+      end
+
+
+      def encrypt(contents)
+        check_key_length
+        encryptor.encrypt_and_sign contents
+      end
+
+      def decrypt(contents)
+        encryptor.decrypt_and_verify contents
+      end
+
+      def encryptor
+        @encryptor ||= ActiveSupport::MessageEncryptor.new([ key ].pack("H*"), cipher: CIPHER, serializer: Marshal)
+      end
+
+
+      def read_env_key
+        ENV[env_key].presence
+      end
+
+      def read_key_file
+        @key_file_contents ||= (key_path.binread.strip if key_path.exist?)
+      end
+
+      def handle_missing_key
+        raise MissingKeyError.new(key_path: key_path, env_key: env_key) if raise_if_missing_key
+      end
+
+      def check_key_length
+        raise InvalidKeyLengthError if key&.length != self.class.expected_key_length
+      end
+  end
+end

data/lib/active_support/environment_inquirer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_support/string_inquirer"
+require "active_support/core_ext/object/inclusion"
+
+module ActiveSupport
+  class EnvironmentInquirer < StringInquirer # :nodoc:
+    # Optimization for the three default environments, so this inquirer doesn't need to rely on
+    # the slower delegation through method_missing that StringInquirer would normally entail.
+    DEFAULT_ENVIRONMENTS = %w[ development test production ]
+
+    # Environments that'll respond true for #local?
+    LOCAL_ENVIRONMENTS = %w[ development test ]
+
+    def initialize(env)
+      raise(ArgumentError, "'local' is a reserved environment name") if env == "local"
+
+      super(env)
+
+      DEFAULT_ENVIRONMENTS.each do |default|
+        instance_variable_set :"@#{default}", env == default
+      end
+
+      @local = in? LOCAL_ENVIRONMENTS
+    end
+
+    DEFAULT_ENVIRONMENTS.each do |env|
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{env}?
+          @#{env}
+        end
+      RUBY
+    end
+
+    # Returns true if we're in the development or test environment.
+    def local?
+      @local
+    end
+  end
+end

data/lib/active_support/error_reporter/test_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveSupport::ErrorReporter::TestHelper # :nodoc:
+  class ErrorSubscriber
+    attr_reader :events
+
+    def initialize
+      @events = []
+    end
+
+    def report(error, handled:, severity:, source:, context:)
+      @events << [error, handled, severity, source, context]
+    end
+  end
+end

data/lib/active_support/error_reporter.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  # = Active Support \Error Reporter
+  #
+  # +ActiveSupport::ErrorReporter+ is a common interface for error reporting services.
+  #
+  # To rescue and report any unhandled error, you can use the #handle method:
+  #
+  #   Rails.error.handle do
+  #     do_something!
+  #   end
+  #
+  # If an error is raised, it will be reported and swallowed.
+  #
+  # Alternatively, if you want to report the error but not swallow it, you can use #record:
+  #
+  #   Rails.error.record do
+  #     do_something!
+  #   end
+  #
+  # Both methods can be restricted to handle only a specific error class:
+  #
+  #   maybe_tags = Rails.error.handle(Redis::BaseError) { redis.get("tags") }
+  #
+  class ErrorReporter
+    SEVERITIES = %i(error warning info)
+    DEFAULT_SOURCE = "application"
+    DEFAULT_RESCUE = [StandardError].freeze
+
+    attr_accessor :logger, :debug_mode
+
+    UnexpectedError = Class.new(Exception)
+
+    def initialize(*subscribers, logger: nil)
+      @subscribers = subscribers.flatten
+      @logger = logger
+      @debug_mode = false
+      @context_middlewares = ErrorContextMiddlewareStack.new
+    end
+
+    # Evaluates the given block, reporting and swallowing any unhandled error.
+    # If no error is raised, returns the return value of the block. Otherwise,
+    # returns the result of +fallback.call+, or +nil+ if +fallback+ is not
+    # specified.
+    #
+    #   # Will report a TypeError to all subscribers and return nil.
+    #   Rails.error.handle do
+    #     1 + '1'
+    #   end
+    #
+    # Can be restricted to handle only specific error classes:
+    #
+    #   maybe_tags = Rails.error.handle(Redis::BaseError) { redis.get("tags") }
+    #
+    # ==== Options
+    #
+    # * +:severity+ - This value is passed along to subscribers to indicate how
+    #   important the error report is. Can be +:error+, +:warning+, or +:info+.
+    #   Defaults to +:warning+.
+    #
+    # * +:context+ - Extra information that is passed along to subscribers. For
+    #   example:
+    #
+    #     Rails.error.handle(context: { section: "admin" }) do
+    #       # ...
+    #     end
+    #
+    # * +:fallback+ - A callable that provides +handle+'s return value when an
+    #   unhandled error is raised. For example:
+    #
+    #     user = Rails.error.handle(fallback: -> { User.anonymous }) do
+    #       User.find_by(params)
+    #     end
+    #
+    # * +:source+ - This value is passed along to subscribers to indicate the
+    #   source of the error. Subscribers can use this value to ignore certain
+    #   errors. Defaults to <tt>"application"</tt>.
+    def handle(*error_classes, severity: :warning, context: {}, fallback: nil, source: DEFAULT_SOURCE)
+      error_classes = DEFAULT_RESCUE if error_classes.empty?
+      yield
+    rescue *error_classes => error
+      report(error, handled: true, severity: severity, context: context, source: source)
+      fallback.call if fallback
+    end
+
+    # Evaluates the given block, reporting and re-raising any unhandled error.
+    # If no error is raised, returns the return value of the block.
+    #
+    #   # Will report a TypeError to all subscribers and re-raise it.
+    #   Rails.error.record do
+    #     1 + '1'
+    #   end
+    #
+    # Can be restricted to handle only specific error classes:
+    #
+    #   tags = Rails.error.record(Redis::BaseError) { redis.get("tags") }
+    #
+    # ==== Options
+    #
+    # * +:severity+ - This value is passed along to subscribers to indicate how
+    #   important the error report is. Can be +:error+, +:warning+, or +:info+.
+    #   Defaults to +:error+.
+    #
+    # * +:context+ - Extra information that is passed along to subscribers. For
+    #   example:
+    #
+    #     Rails.error.record(context: { section: "admin" }) do
+    #       # ...
+    #     end
+    #
+    # * +:source+ - This value is passed along to subscribers to indicate the
+    #   source of the error. Subscribers can use this value to ignore certain
+    #   errors. Defaults to <tt>"application"</tt>.
+    def record(*error_classes, severity: :error, context: {}, source: DEFAULT_SOURCE)
+      error_classes = DEFAULT_RESCUE if error_classes.empty?
+      yield
+    rescue *error_classes => error
+      report(error, handled: false, severity: severity, context: context, source: source)
+      raise
+    end
+
+    # Either report the given error when in production, or raise it when in development or test.
+    #
+    # When called in production, after the error is reported, this method will return
+    # nil and execution will continue.
+    #
+    # When called in development, the original error is wrapped in a different error class to ensure
+    # it's not being rescued higher in the stack and will be surfaced to the developer.
+    #
+    # This method is intended for reporting violated assertions about preconditions, or similar
+    # cases that can and should be gracefully handled in production, but that aren't supposed to happen.
+    #
+    # The error can be either an exception instance or a String.
+    #
+    #   example:
+    #
+    #     def edit
+    #       if published?
+    #         Rails.error.unexpected("[BUG] Attempting to edit a published article, that shouldn't be possible")
+    #         return false
+    #       end
+    #       # ...
+    #     end
+    #
+    def unexpected(error, severity: :warning, context: {}, source: DEFAULT_SOURCE)
+      error = RuntimeError.new(error) if error.is_a?(String)
+
+      if @debug_mode
+        ensure_backtrace(error)
+        raise UnexpectedError, "#{error.class.name}: #{error.message}", error.backtrace, cause: error
+      else
+        report(error, handled: true, severity: severity, context: context, source: source)
+      end
+    end
+
+    # Register a new error subscriber. The subscriber must respond to
+    #
+    #   report(Exception, handled: Boolean, severity: (:error OR :warning OR :info), context: Hash, source: String)
+    #
+    # The +report+ method <b>should never</b> raise an error.
+    def subscribe(subscriber)
+      unless subscriber.respond_to?(:report)
+        raise ArgumentError, "Error subscribers must respond to #report"
+      end
+      @subscribers << subscriber
+    end
+
+    # Unregister an error subscriber. Accepts either a subscriber or a class.
+    #
+    #   subscriber = MyErrorSubscriber.new
+    #   Rails.error.subscribe(subscriber)
+    #
+    #   Rails.error.unsubscribe(subscriber)
+    #   # or
+    #   Rails.error.unsubscribe(MyErrorSubscriber)
+    def unsubscribe(subscriber)
+      @subscribers.delete_if { |s| subscriber === s }
+    end
+
+    # Prevent a subscriber from being notified of errors for the
+    # duration of the block. You may pass in the subscriber itself, or its class.
+    #
+    # This can be helpful for error reporting service integrations, when they wish
+    # to handle any errors higher in the stack.
+    def disable(subscriber)
+      disabled_subscribers = (ActiveSupport::IsolatedExecutionState[self] ||= [])
+      disabled_subscribers << subscriber
+      begin
+        yield
+      ensure
+        disabled_subscribers.delete(subscriber)
+      end
+    end
+
+    # Update the execution context that is accessible to error subscribers. Any
+    # context passed to #handle, #record, or #report will be merged with the
+    # context set here.
+    #
+    #   Rails.error.set_context(section: "checkout", user_id: @user.id)
+    #
+    def set_context(...)
+      ActiveSupport::ExecutionContext.set(...)
+    end
+
+    # Add a middleware to modify the error context before it is sent to subscribers.
+    #
+    # Middleware is added to a stack of callables run on an error's execution context
+    # before passing to subscribers. Allows creation of entries in error context that
+    # are shared by all subscribers.
+    #
+    # A context middleware receives the same parameters as #report.
+    # It must return a hash - the middleware stack returns the hash after it has
+    # run through all middlewares. A middleware can mutate or replace the hash.
+    #
+    #   Rails.error.add_middleware(-> (error, context) { context.merge({ foo: :bar }) })
+    #
+    def add_middleware(middleware)
+      @context_middlewares.use(middleware)
+    end
+
+    # Report an error directly to subscribers. You can use this method when the
+    # block-based #handle and #record methods are not suitable.
+    #
+    #   Rails.error.report(error)
+    #
+    # The +error+ argument must be an instance of Exception.
+    #
+    #   Rails.error.report(Exception.new("Something went wrong"))
+    #
+    # Otherwise you can use #unexpected to report an error which does accept a
+    # string argument.
+    def report(error, handled: true, severity: handled ? :warning : :error, context: {}, source: DEFAULT_SOURCE)
+      return if error.instance_variable_defined?(:@__rails_error_reported)
+      raise ArgumentError, "Reported error must be an Exception, got: #{error.inspect}" unless error.is_a?(Exception)
+
+      ensure_backtrace(error)
+
+      unless SEVERITIES.include?(severity)
+        raise ArgumentError, "severity must be one of #{SEVERITIES.map(&:inspect).join(", ")}, got: #{severity.inspect}"
+      end
+
+      full_context = @context_middlewares.execute(
+        error,
+        context: ActiveSupport::ExecutionContext.to_h.merge(context || {}),
+        handled:,
+        severity:,
+        source:
+      )
+
+      disabled_subscribers = ActiveSupport::IsolatedExecutionState[self]
+      @subscribers.each do |subscriber|
+        unless disabled_subscribers&.any? { |s| s === subscriber }
+          subscriber.report(error, handled: handled, severity: severity, context: full_context, source: source)
+        end
+      rescue => subscriber_error
+        if logger
+          logger.fatal(
+            "Error subscriber raised an error: #{subscriber_error.message} (#{subscriber_error.class})\n" +
+            subscriber_error.backtrace.join("\n")
+          )
+        else
+          raise
+        end
+      end
+
+      while error
+        unless error.frozen?
+          error.instance_variable_set(:@__rails_error_reported, true)
+        end
+        error = error.cause
+      end
+
+      nil
+    end
+
+    private
+      def ensure_backtrace(error)
+        return if error.frozen? # re-raising won't add a backtrace or set the cause
+        return unless error.backtrace.nil?
+
+        begin
+          # As of Ruby 3.4, we could use Exception#set_backtrace to set the backtrace,
+          # but there's nothing like Exception#set_cause. Raising+rescuing is the only way to set the cause.
+          raise error
+        rescue error.class => error
+        end
+
+        count = 0
+        while error.backtrace_locations.first&.path == __FILE__
+          count += 1
+          error.backtrace_locations.shift
+        end
+
+        error.backtrace.shift(count)
+      end
+
+      class ErrorContextMiddlewareStack # :nodoc:
+        def initialize
+          @stack = []
+        end
+
+        # Add a middleware to the error context stack.
+        def use(middleware)
+          unless middleware.respond_to?(:call)
+            raise ArgumentError, "Error context middleware must respond to #call"
+          end
+
+          @stack << middleware
+        end
+
+        # Run all middlewares in the stack
+        def execute(error, handled:, severity:, context:, source:)
+          @stack.inject(context) { |c, middleware| middleware.call(error, context: c, handled:, severity:, source:) }
+        end
+      end
+  end
+end

data/lib/active_support/event_reporter/test_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveSupport::EventReporter::TestHelper # :nodoc:
+  class EventSubscriber # :nodoc:
+    attr_reader :events
+
+    def initialize
+      @events = []
+    end
+
+    def emit(event)
+      @events << event
+    end
+  end
+
+  def event_matcher(name:, payload: nil, tags: {}, context: {}, source_location: nil)
+    ->(event) {
+      return false unless event[:name] == name
+      return false unless event[:payload] == payload
+      return false unless event[:tags] == tags
+      return false unless event[:context] == context
+
+      [:filepath, :lineno, :label].each do |key|
+        if source_location && source_location[key]
+          return false unless event[:source_location][key] == source_location[key]
+        end
+      end
+
+      true
+    }
+  end
+end