airbrake-ruby 1.0.0.rc.1

data/lib/airbrake-ruby/config.rb

@@ -0,0 +1,120 @@
+module Airbrake
+  ##
+  # Represents the Airbrake config. A config contains all the options that you
+  # can use to configure an Airbrake instance.
+  class Config
+    ##
+    # @return [Integer] the project identificator. This value *must* be set.
+    attr_accessor :project_id
+
+    ##
+    # @return [String] the project key. This value *must* be set.
+    attr_accessor :project_key
+
+    ##
+    # @return [Hash] the proxy parameters such as (:host, :port, :user and
+    #   :password)
+    attr_accessor :proxy
+
+    ##
+    # @return [Logger] the default logger used for debug output
+    attr_reader :logger
+
+    ##
+    # @return [String] the version of the user's application
+    attr_accessor :app_version
+
+    ##
+    # @return [Integer] the max number of notices that can be queued up
+    attr_accessor :queue_size
+
+    ##
+    # @return [Integer] the number of worker threads that process the notice
+    #   queue
+    attr_accessor :workers
+
+    ##
+    # @return [String] the host, which provides the API endpoint to which
+    #   exceptions should be sent
+    attr_accessor :host
+
+    ##
+    # @return [String, Pathname] the working directory of your project
+    attr_accessor :root_directory
+
+    ##
+    # @return [String, Symbol] the environment the application is running in
+    attr_accessor :environment
+
+    ##
+    # @return [Array<String, Symbol>] the array of environments that forbids
+    #   sending exceptions when the application is running in them. Other
+    #   possible environments not listed in the array will allow sending
+    #   occurring exceptions.
+    attr_accessor :ignore_environments
+
+    ##
+    # @param [Hash{Symbol=>Object}] user_config the hash to be used to build the
+    #   config
+    def initialize(user_config = {})
+      self.proxy = {}
+      self.queue_size = 100
+      self.workers = 1
+
+      self.logger = Logger.new(STDOUT)
+      logger.level = Logger::WARN
+
+      self.project_id = user_config[:project_id]
+      self.project_key = user_config[:project_key]
+      self.host = 'https://airbrake.io'
+
+      self.ignore_environments = []
+
+      merge(user_config)
+    end
+
+    ##
+    # The full URL to the Airbrake Notice API. Based on the +:host+ option.
+    # @return [URI] the endpoint address
+    def endpoint
+      @endpoint ||=
+        begin
+          self.host = ('https://' << host) if host !~ %r{\Ahttps?://}
+          api = "/api/v3/projects/#{project_id}/notices?key=#{project_key}"
+          URI.join(host, api)
+        end
+    end
+
+    ##
+    # Sets the logger. Never allows to assign `nil` as the logger.
+    # @return [Logger] the logger
+    def logger=(logger)
+      @logger = logger || @logger
+    end
+
+    ##
+    # Merges the given +config_hash+ with itself.
+    #
+    # @example
+    #   config.merge(host: 'localhost:8080')
+    #
+    # @return [self] the merged config
+    def merge(config_hash)
+      config_hash.each_pair { |option, value| set_option(option, value) }
+      self
+    end
+
+    private
+
+    def set_option(option, value)
+      __send__("#{option}=", value)
+    rescue NoMethodError
+      raise Airbrake::Error, "unknown option '#{option}'"
+    end
+
+    def set_endpoint(id, key, host)
+      host = ('https://' << host) if host !~ %r{\Ahttps?://}
+      @endpoint = URI.join(host, "/api/v3/projects/#{id}/notices?key=#{key}")
+    end
+  end
+end

data/lib/airbrake-ruby/filter_chain.rb

@@ -0,0 +1,86 @@
+module Airbrake
+  ##
+  # Represents the mechanism for filtering notices. Defines a few default
+  # filters.
+  # @see Airbrake.add_filter
+  class FilterChain
+    ##
+    # Replaces paths to gems with a placeholder.
+    # @return [Proc]
+    GEM_ROOT_FILTER = proc do |notice|
+      return unless defined?(Gem)
+
+      notice[:errors].each do |error|
+        Gem.path.each do |gem_path|
+          error[:backtrace].each do |frame|
+            frame[:file].sub!(/\A#{gem_path}/, '[GEM_ROOT]'.freeze)
+          end
+        end
+      end
+    end
+
+    ##
+    # Skip over SystemExit exceptions, because they're just noise.
+    # @return [Proc]
+    SYSTEM_EXIT_FILTER = proc do |notice|
+      if notice[:errors].any? { |error| error[:type] == 'SystemExit' }
+        notice.ignore!
+      end
+    end
+
+    ##
+    # @param [Airbrake::Config] config
+    def initialize(config)
+      @filters = []
+
+      if config.ignore_environments.any?
+        add_filter(env_filter(config.environment, config.ignore_environments))
+      end
+
+      [SYSTEM_EXIT_FILTER, GEM_ROOT_FILTER].each do |filter|
+        add_filter(filter)
+      end
+
+      root_directory = config.root_directory
+      add_filter(root_directory_filter(root_directory)) if root_directory
+    end
+
+    ##
+    # Adds a filter to the filter chain.
+    # @param [#call] filter The filter object (proc, class, module, etc)
+    def add_filter(filter)
+      @filters << filter
+    end
+
+    ##
+    # Applies all the filters in the filter chain to the given notice. Does not
+    # filter ignored notices.
+    #
+    # @param [Airbrake::Notice] notice The notice to be filtered
+    # @return [void]
+    def refine(notice)
+      @filters.each do |filter|
+        break if notice.ignored?
+        filter.call(notice)
+      end
+    end
+
+    private
+
+    def root_directory_filter(root_directory)
+      proc do |notice|
+        notice[:errors].each do |error|
+          error[:backtrace].each do |frame|
+            frame[:file].sub!(/\A#{root_directory}/, '[PROJECT_ROOT]'.freeze)
+          end
+        end
+      end
+    end
+
+    def env_filter(environment, ignore_environments)
+      proc do |notice|
+        notice.ignore! if ignore_environments.include?(environment)
+      end
+    end
+  end
+end

data/lib/airbrake-ruby/filters.rb

@@ -0,0 +1,10 @@
+module Airbrake
+  ##
+  # Represents a namespace for default Airbrake Ruby filters.
+  module Filters
+    ##
+    # @return [Array<Symbol>] parts of a Notice's payload that can be modified
+    #   by various filters
+    FILTERABLE_KEYS = [:environment, :session, :params].freeze
+  end
+end

data/lib/airbrake-ruby/filters/keys_blacklist.rb

@@ -0,0 +1,37 @@
+module Airbrake
+  module Filters
+    ##
+    # A default Airbrake notice filter. Filters only specific keys listed in the
+    # list of parameters in the modifiable payload of a notice.
+    #
+    # @example
+    #   filter = Airbrake::Filters::KeysBlacklist.new(:email, /credit/i, 'password')
+    #   airbrake.add_filter(filter)
+    #   airbrake.notify(StandardError.new('App crashed!'), {
+    #     user: 'John'
+    #     password: 's3kr3t',
+    #     email: 'john@example.com',
+    #     credit_card: '5555555555554444'
+    #   })
+    #
+    #   # The dashboard will display this parameter as is, but all other
+    #   # values will be filtered:
+    #   #   { user: 'John',
+    #   #     password: '[Filtered]',
+    #   #     email: '[Filtered]',
+    #   #     credit_card: '[Filtered]' }
+    #
+    # @see KeysWhitelist
+    # @see KeysFilter
+    class KeysBlacklist
+      include KeysFilter
+
+      ##
+      # @return [Boolean] true if the key matches at least one pattern, false
+      #   otherwise
+      def should_filter?(key)
+        @patterns.any? { |pattern| key.to_s.match(pattern) }
+      end
+    end
+  end
+end

data/lib/airbrake-ruby/filters/keys_filter.rb

@@ -0,0 +1,65 @@
+module Airbrake
+  module Filters
+    ##
+    # This is a filter helper that endows a class ability to filter notices'
+    # payload based on the return value of the +should_filter?+ method that a
+    # class that includes this module must implement.
+    #
+    # @see Notice
+    # @see KeysWhitelist
+    # @see KeysBlacklist
+    module KeysFilter
+      ##
+      # Creates a new KeysBlacklist or KeysWhitelist filter that uses the given
+      # +patterns+ for filtering a notice's payload.
+      #
+      # @param [Array<String,Regexp,Symbol>] patterns
+      def initialize(*patterns)
+        @patterns = patterns.map(&:to_s)
+      end
+
+      ##
+      # This is a mandatory method required by any filter integrated with
+      # FilterChain.
+      #
+      # @param [Notice] notice the notice to be filtered
+      # @return [void]
+      # @see FilterChain
+      def call(notice)
+        FILTERABLE_KEYS.each { |key| filter_hash(notice[key]) }
+
+        return unless notice[:context][:url]
+        url = URI(notice[:context][:url])
+        return if url.nil? || url.query.nil?
+
+        notice[:context][:url] = filter_url_params(url)
+      end
+
+      ##
+      # @raise [NotImplementedError] if called directly
+      def should_filter?(_key)
+        raise NotImplementedError, 'method must be implemented in the included class'
+      end
+
+      private
+
+      def filter_hash(hash)
+        hash.each_key do |key|
+          if should_filter?(key)
+            hash[key] = '[Filtered]'.freeze
+          else
+            filter_hash(hash[key]) if hash[key].is_a?(Hash)
+          end
+        end
+      end
+
+      def filter_url_params(url)
+        url.query = Hash[URI.decode_www_form(url.query)].map do |key, val|
+          should_filter?(key) ? "#{key}=[Filtered]" : "#{key}=#{val}"
+        end.join('&')
+
+        url.to_s
+      end
+    end
+  end
+end

data/lib/airbrake-ruby/filters/keys_whitelist.rb

@@ -0,0 +1,37 @@
+module Airbrake
+  module Filters
+    ##
+    # A default Airbrake notice filter. Filters everything in the modifiable
+    # payload of a notice, but specified keys.
+    #
+    # @example
+    #   filter = Airbrake::Filters::KeysWhitelist.new(:email, /user/i, 'account_id')
+    #   airbrake.add_filter(filter)
+    #   airbrake.notify(StandardError.new('App crashed!'), {
+    #     user: 'John',
+    #     password: 's3kr3t',
+    #     email: 'john@example.com',
+    #     account_id: 42
+    #   })
+    #
+    #   # The dashboard will display this parameters as filtered, but other
+    #   # values won't be affected:
+    #   #   { user: 'John',
+    #   #     password: '[Filtered]',
+    #   #     email: 'john@example.com',
+    #   #     account_id: 42 }
+    #
+    # @see KeysBlacklist
+    # @see KeysFilter
+    class KeysWhitelist
+      include KeysFilter
+
+      ##
+      # @return [Boolean] true if the key doesn't match any pattern, false
+      #   otherwise.
+      def should_filter?(key)
+        @patterns.none? { |pattern| key.to_s.match(pattern) }
+      end
+    end
+  end
+end

data/lib/airbrake-ruby/notice.rb

@@ -0,0 +1,207 @@
+module Airbrake
+  ##
+  # Represents a chunk of information that is meant to be either sent to
+  # Airbrake or ignored completely.
+  class Notice
+    # @return [Hash{Symbol=>String}] the information about the notifier library
+    NOTIFIER = {
+      name: 'airbrake-ruby'.freeze,
+      version: Airbrake::AIRBRAKE_RUBY_VERSION,
+      url: 'https://github.com/airbrake/airbrake-ruby'.freeze
+    }.freeze
+
+    ##
+    # @return [Hash{Symbol=>String,Hash}] the information to be displayed in the
+    #   Context tab in the dashboard
+    CONTEXT = {
+      os: RUBY_PLATFORM,
+      language: RUBY_VERSION,
+      notifier: NOTIFIER
+    }.freeze
+
+    ##
+    # @return [Integer] the maxium size of the JSON payload in bytes
+    MAX_NOTICE_SIZE = 64000
+
+    ##
+    # @return [Integer] the maximum number of nested exceptions that a notice
+    #   can unwrap. Exceptions that have a longer cause chain will be ignored
+    MAX_NESTED_EXCEPTIONS = 3
+
+    ##
+    # @return [Integer] the maximum size of hashes, arrays and strings in the
+    #   notice.
+    PAYLOAD_MAX_SIZE = 10000
+
+    ##
+    # @return [Array<StandardError>] the list of possible exceptions that might
+    #   be raised when an object is converted to JSON
+    JSON_EXCEPTIONS = [
+      IOError,
+      NotImplementedError,
+      JSON::GeneratorError,
+      Encoding::UndefinedConversionError
+    ]
+
+    # @return [Array<Symbol>] the list of keys that can be be overwritten with
+    #   {Airbrake::Notice#[]=}
+    WRITABLE_KEYS = [
+      :notifier,
+      :context,
+      :environment,
+      :session,
+      :params
+    ]
+
+    def initialize(config, exception, params = {})
+      @config = config
+
+      @private_payload = {
+        notifier: NOTIFIER
+      }.freeze
+
+      @modifiable_payload = {
+        errors: errors(exception),
+        context: context(params),
+        environment: {},
+        session: {},
+        params: params
+      }
+
+      @truncator = PayloadTruncator.new(PAYLOAD_MAX_SIZE, @config.logger)
+    end
+
+    ##
+    # Converts the notice to JSON. Calls +to_json+ on each object inside
+    # notice's payload. Truncates notices, JSON representation of which is
+    # bigger than {MAX_NOTICE_SIZE}.
+    #
+    # @return [Hash{String=>String}]
+    def to_json
+      loop do
+        begin
+          json = payload.to_json
+        rescue *JSON_EXCEPTIONS => ex
+          @config.logger.debug("#{LOG_LABEL} `notice.to_json` failed: #{ex.to_s.chomp}")
+        else
+          return json if json && json.bytesize <= MAX_NOTICE_SIZE
+        end
+
+        truncate_payload
+      end
+    end
+
+    ##
+    # Ignores a notice. Ignored notices never reach the Airbrake dashboard.
+    #
+    # @return [void]
+    # @see #ignored?
+    # @note Ignored noticed can't be unignored
+    def ignore!
+      @modifiable_payload = nil
+    end
+
+    ##
+    # Checks whether the notice was ignored.
+    #
+    # @return [Boolean]
+    # @see #ignore!
+    def ignored?
+      @modifiable_payload.nil?
+    end
+
+    ##
+    # Reads a value from notice's modifiable payload.
+    # @return [Object]
+    #
+    # @raise [Airbrake::Error] if the notice is ignored
+    def [](key)
+      raise_if_ignored
+      @modifiable_payload[key]
+    end
+
+    ##
+    # Writes a value to the modifiable payload hash. Restricts unrecognized
+    # writes.
+    # @example
+    #   notice[:params][:my_param] = 'foobar'
+    #
+    # @return [void]
+    # @raise [Airbrake::Error] if the notice is ignored
+    # @raise [Airbrake::Error] if the +key+ is not recognized
+    # @raise [Airbrake::Error] if the root value is not a Hash
+    def []=(key, value)
+      raise_if_ignored
+      raise_if_unrecognized_key(key)
+      raise_if_non_hash_value(value)
+
+      @modifiable_payload[key] = value.to_hash
+    end
+
+    private
+
+    def context(params)
+      { version: @config.app_version,
+        # We ensure that root_directory is always a String, so it can always be
+        # converted to JSON in a predictable manner (when it's a Pathname and in
+        # Rails environment, it converts to unexpected JSON).
+        rootDirectory: @config.root_directory.to_s,
+        environment: @config.environment,
+
+        # Legacy Airbrake v4 behaviour.
+        component: params.delete(:component),
+        action: params.delete(:action)
+      }.merge(CONTEXT).delete_if { |_key, val| val.nil? || val.empty? }
+    end
+
+    def raise_if_ignored
+      return unless self.ignored?
+      raise Airbrake::Error, 'cannot access ignored notice'
+    end
+
+    def raise_if_unrecognized_key(key)
+      return if WRITABLE_KEYS.include?(key)
+      raise Airbrake::Error,
+            ":#{key} is not recognized among #{WRITABLE_KEYS}"
+    end
+
+    def raise_if_non_hash_value(value)
+      return if value.respond_to?(:to_hash)
+      raise Airbrake::Error, "Got #{value.class} value, wanted a Hash"
+    end
+
+    def payload
+      @modifiable_payload.merge(@private_payload)
+    end
+
+    def errors(exception)
+      exception_list = []
+
+      while exception && exception_list.size < MAX_NESTED_EXCEPTIONS
+        exception_list << exception
+
+        exception = if exception.respond_to?(:cause) && exception.cause
+                      exception.cause
+                    end
+      end
+
+      exception_list.map do |e|
+        { type: e.class.name,
+          message: e.message,
+          backtrace: Backtrace.parse(e) }
+      end
+    end
+
+    def truncate_payload
+      @modifiable_payload[:errors].each do |error|
+        @truncator.truncate_error(error)
+      end
+
+      Filters::FILTERABLE_KEYS.each do |key|
+        @truncator.truncate_object(@modifiable_payload[key])
+      end
+
+      @truncator.reduce_max_size
+    end
+  end
+end