honeybadger 3.2.0 → 3.3.0

data/lib/honeybadger/backend/base.rb

@@ -18,17 +18,20 @@ module Honeybadger
         403 => "The API key is invalid. Please check your API key and try again.".freeze
       }.freeze
 
-      # Public: Initializes the Response instance.
+      # Initializes the Response instance.
       #
-      # response - With 1 argument Net::HTTPResponse, the code, body, and
-      #            message will be determined automatically (optional).
-      # code      - The Integer status code. May also be :error for requests which
-      #             failed to reach the server.
-      # body      - The String body of the response.
-      # message   - The String message returned by the server (or set by the
-      #             backend in the case of an :error code).
+      # @overload initialize(response)
+      #   Creates an instance from a +Net::HTTPResponse+.
+      #   @param [Net::HTTPResponse] response With 1 argument, the code, body,
+      #     and message will be determined automatically.
       #
-      # Returns nothing
+      # @overload initialize(code, body, message)
+      #   Creates an instance from parameters.
+      #   @param [Integer] code The status code. May also be :error for requests
+      #     which failed to reach the server.
+      #   @param [String] body The String body of the response.
+      #   @param [String] message The String message returned by the server (or
+      #     set by the backend in the case of an :error code).
       def initialize(*args)
         if (response = args.first).kind_of?(Net::HTTPResponse)
           @code, @body, @message = response.code.to_i, response.body.to_s, response.message
@@ -73,26 +76,25 @@ module Honeybadger
         @config = config
       end
 
-      # Internal: Process payload for feature.
-      #
-      # feature - A Symbol feature name (corresponds to HTTP endpoint). Current
-      #           options are: `:notices`, `:deploys`, `:ping`.
-      # payload - Any Object responding to `#to_json`.
-      #
-      # Examples
+      # Process payload for feature.
       #
+      # @example
       #   backend.notify(:notices, Notice.new(...))
       #
-      # Raises NotImplementedError
+      # @param [Symbol] feature The feature name (corresponds to HTTP
+      #   endpoint). Current options are: `:notices`, `:deploys`, `:ping`.
+      # @param [#to_json] payload The JSON payload to send.
+      #
+      # @raise NotImplementedError
       def notify(feature, payload)
         raise NotImplementedError, 'must define #notify on subclass.'
       end
 
-      # Internal: Does a check in using the input id.
+      # Does a check in using the input id.
       #
-      # id - The unique check_in id.
+      # @param [String] id The unique check_in id.
       #
-      # Raises NotImplementedError.
+      # @raise NotImplementedError
       def check_in(id)
         raise NotImplementedError, 'must define #check_in on subclass.'
       end

data/lib/honeybadger/backend/debug.rb

@@ -2,9 +2,9 @@ require 'honeybadger/backend/null'
 
 module Honeybadger
   module Backend
-    # Internal: Logs the notice payload rather than sending it. The purpose of
-    # this backend is primarily for programmatically inspecting JSON payloads
-    # in integration tests.
+    # Logs the notice payload rather than sending it. The purpose of this
+    # backend is primarily for programmatically inspecting JSON payloads in
+    # integration tests.
     class Debug < Null
       def notify(feature, payload)
         logger.unknown("notifying debug backend of feature=#{feature}\n\t#{payload.to_json}")

data/lib/honeybadger/backend/server.rb

@@ -24,12 +24,12 @@ module Honeybadger
         super
       end
 
-      # Internal: Post payload to endpoint for feature.
+      # Post payload to endpoint for feature.
       #
-      # feature - The feature which is being notified.
-      # payload - The payload to send, responding to `#to_json`.
+      # @param [Symbol] feature The feature which is being notified.
+      # @param [#to_json] payload The JSON payload to send.
       #
-      # Returns Response.
+      # @return [Response]
       def notify(feature, payload)
         ENDPOINTS[feature] or raise(BackendError, "Unknown feature: #{feature}")
         Response.new(@http.post(ENDPOINTS[feature], payload, payload_headers(payload)))
@@ -37,11 +37,11 @@ module Honeybadger
         Response.new(:error, nil, "HTTP Error: #{e.class}")
       end
 
-      # Internal: Does a check in using the input id.
+      # Does a check in using the input id.
       #
-      # id - The unique check_in id.
+      # @param [String] id The unique check_in id.
       #
-      # Returns Response.
+      # @return [Response]
       def check_in(id)
         Response.new(@http.get("#{CHECK_IN_ENDPOINT}/#{id}"))
       rescue *HTTP_ERRORS => e
@@ -50,11 +50,6 @@ module Honeybadger
 
       private
 
-      # Internal: Construct headers for supported payloads.
-      #
-      # payload - The payload object.
-      #
-      # Returns Hash headers if supported, otherwise nil.
       def payload_headers(payload)
         if payload.respond_to?(:api_key) && payload.api_key
           {

data/lib/honeybadger/backend/test.rb

@@ -3,34 +3,31 @@ require 'honeybadger/backend/null'
 module Honeybadger
   module Backend
     class Test < Null
-      # Public: The notification list.
-      #
-      # Examples
+      # The notification list.
       #
+      # @example
       #   Test.notifications[:notices] # => [Notice, Notice, ...]
       #
-      # Returns the Hash notifications.
+      # @return [Hash] Notifications hash.
       def self.notifications
         @notifications ||= Hash.new {|h,k| h[k] = [] }
       end
 
-      # Public: The check in list.
-      #
-      # Examples
+      # @api public
+      # The check in list.
       #
+      # @example
       #   Test.check_ins # => ["foobar", "danny", ...]
       #
-      # Returns the Array of check ins.
+      # @return [Array<Object>] List of check ins.
       def self.check_ins
         @check_ins ||= []
       end
 
-      # Internal: Local helper.
       def notifications
         self.class.notifications
       end
 
-      # Internal: Local helper.
       def check_ins
         self.class.check_ins
       end

data/lib/honeybadger/backtrace.rb

@@ -1,20 +1,21 @@
 require 'json'
 
 module Honeybadger
-  # Internal: Front end to parsing the backtrace for each notice
+  # @api private
+  # Front end to parsing the backtrace for each notice.
   class Backtrace
-    # Internal: Handles backtrace parsing line by line
+    # Handles backtrace parsing line by line.
     class Line
-      # Backtrace line regexp (optionally allowing leading X: for windows support)
+      # Backtrace line regexp (optionally allowing leading X: for windows support).
       INPUT_FORMAT = %r{^((?:[a-zA-Z]:)?[^:]+):(\d+)(?::in `([^']+)')?$}.freeze
 
-      # The file portion of the line (such as app/models/user.rb)
+      # The file portion of the line (such as app/models/user.rb).
       attr_reader :file
 
-      # The line number portion of the line
+      # The line number portion of the line.
       attr_reader :number
 
-      # The method of the line (such as index)
+      # The method of the line (such as index).
       attr_reader :method
 
       # Filtered representations
@@ -22,9 +23,9 @@ module Honeybadger
 
       # Parses a single line of a given backtrace
       #
-      # unparsed_line - The raw line from +caller+ or some backtrace
+      # @param [String] unparsed_line The raw line from +caller+ or some backtrace.
       #
-      # Returns the parsed backtrace line
+      # @return The parsed backtrace line.
       def self.parse(unparsed_line, opts = {})
         filters = opts[:filters] || []
         filtered_line = filters.reduce(unparsed_line) do |line, proc|

data/lib/honeybadger/cli.rb

@@ -5,6 +5,7 @@ require 'thor'
 require 'honeybadger/cli/main'
 
 module Honeybadger
+  # @api private
   module CLI
     def self.start(*args)
       Main.start(*args)

data/lib/honeybadger/cli/heroku.rb

@@ -53,10 +53,10 @@ module Honeybadger
 
       private
 
-      # Internal: Detects the Heroku app name from GIT.
+      # Detects the Heroku app name from GIT.
       #
-      # prompt_on_default - If a single remote is discoverd, should we prompt the
-      #                     user before returning it?
+      # @param [Boolean] prompt_on_default If a single remote is discoverd,
+      #   should we prompt the user before returning it?
       #
       # Returns the String app name if detected, otherwise nil.
       def detect_heroku_app(prompt_on_default = true)

data/lib/honeybadger/cli/test.rb

@@ -141,7 +141,7 @@ module Honeybadger
             r.disable_clear_and_finalize = true
             r.clear!
             r.draw do
-              match 'verify' => 'honeybadger/test#verify', :as => 'verify', :via => :get
+              match 'verify' => 'honeybadger/test#verify', :as => "verify_#{SecureRandom.hex}", :via => :get
             end
             ::Rails.application.routes_reloader.paths.each{ |path| load(path) }
             ::ActiveSupport.on_load(:action_controller) { r.finalize! }

data/lib/honeybadger/config.rb

@@ -13,9 +13,9 @@ require 'honeybadger/util/revision'
 require 'honeybadger/logging'
 
 module Honeybadger
-  # Internal: The Config class is used to manage Honeybadger's initialization
-  # and configuration. Please don't depend on any internal classes or methods
-  # outside of Honeybadger as they may change without notice.
+  # @api private
+  # The Config class is used to manage Honeybadger's initialization and
+  # configuration.
   class Config
     extend Forwardable
 
@@ -125,6 +125,7 @@ module Honeybadger
 
     # Internal Helpers
 
+
     def logger
       init_logging! unless @logger
       @logger
@@ -241,9 +242,6 @@ module Honeybadger
       includes_token?(self[:plugins], name)
     end
 
-    # Match the project root.
-    #
-    # Returns Regexp matching the project root in a file string.
     def root_regexp
       return @root_regexp if @root_regexp
       return nil if @no_root
@@ -285,19 +283,12 @@ module Honeybadger
       set(:revision, Util::Revision.detect(self[:root]))
     end
 
-    # Optional path to honeybadger.log log file.
-    #
-    # Returns the Pathname log path if a log path was specified.
     def log_path
       return if log_stdout?
       return if !self[:'logging.path']
       locate_absolute_path(self[:'logging.path'], self[:root])
     end
 
-    # Path to honeybadger.yml configuration file; this should be the
-    # root directory if no path was specified.
-    #
-    # Returns the Pathname configuration path.
     def config_path
       config_paths.first
     end
@@ -370,12 +361,8 @@ module Honeybadger
       @logger = Logging::ConfigLogger.new(self, build_logger)
     end
 
-    # Does collection include the String value or Symbol value?
-    #
-    # obj - The Array object, if present.
-    # value - The value which may exist within Array obj.
-    #
-    # Returns true or false.
+    # Takes an Array and a value and returns true if the value exists in the
+    # array in String or Symbol form, otherwise false.
     def includes_token?(obj, value)
       return false unless obj.kind_of?(Array)
       obj.map(&:to_sym).include?(value.to_sym)

data/lib/honeybadger/config/defaults.rb

@@ -17,6 +17,8 @@ module Honeybadger
                       'ActionController::ParameterMissing',
                       'ActiveRecord::RecordNotFound',
                       'ActionController::UnknownAction',
+                      'Rack::QueryParser::ParameterTypeError',
+                      'Rack::QueryParser::InvalidParameterError',
                       'CGI::Session::CookieStore::TamperedWithCookie',
                       'Mongoid::Errors::DocumentNotFound',
                       'Sinatra::NotFound'].map(&:freeze).freeze

data/lib/honeybadger/const.rb

@@ -1,12 +1,20 @@
 require 'honeybadger/version'
 
 module Honeybadger
-  # Autoloading allows middleware classes to be referenced in applications
-  # which include the optional Rack dependency without explicitly requiring
-  # these files.
   module Rack
+    # Autoloading allows middleware classes to be referenced in applications
+    # which include the optional Rack dependency without explicitly requiring
+    # these files.
     autoload :ErrorNotifier, 'honeybadger/rack/error_notifier'
     autoload :UserFeedback, 'honeybadger/rack/user_feedback'
     autoload :UserInformer, 'honeybadger/rack/user_informer'
   end
+
+  # @api private
+  module Plugins
+  end
+
+  # @api private
+  module Util
+  end
 end

data/lib/honeybadger/context_manager.rb

@@ -1,6 +1,7 @@
 require 'honeybadger/conversions'
 
 module Honeybadger
+  # @api private
   class ContextManager
     include Conversions
 
@@ -17,7 +18,8 @@ module Honeybadger
       _initialize
     end
 
-    # Internal accessors
+    # Internal helpers
+
 
     def set_context(hash)
       @mutex.synchronize do

data/lib/honeybadger/conversions.rb

@@ -1,12 +1,13 @@
 module Honeybadger
+  # @api private
   module Conversions
     module_function
 
-    # Internal: Convert context into a Hash.
+    # Convert context into a Hash.
     #
-    # object - The context object.
+    # @param [Object] object The context object.
     #
-    # Returns the Hash context.
+    # @return [Hash] The hash context.
     def Context(object)
       object = object.to_honeybadger_context if object.respond_to?(:to_honeybadger_context)
       Hash(object)

data/lib/honeybadger/init/rails.rb

@@ -31,3 +31,5 @@ module Honeybadger
     end
   end
 end
+
+Honeybadger.install_at_exit_callback

data/lib/honeybadger/init/rake.rb

@@ -1,7 +1,8 @@
 require 'honeybadger/ruby'
 
-# Patch Rake::Application to handle errors with Honeybadger
 module Honeybadger
+  # @api private
+  # Patch Rake::Application to handle errors with Honeybadger
   module RakeHandler
     def self.included(klass)
       klass.class_eval do

data/lib/honeybadger/init/ruby.rb

@@ -7,3 +7,5 @@ Honeybadger.init!({
 })
 
 Honeybadger.load_plugins!
+
+Honeybadger.install_at_exit_callback

data/lib/honeybadger/init/sinatra.rb

@@ -9,6 +9,9 @@ module Honeybadger
           def build_with_honeybadger(*args, &block)
             configure_honeybadger
             install_honeybadger
+            # Sinatra is a special case. Sinatra starts the web application in an at_exit
+            # handler. And, since we require sinatra before requiring HB, the only way to
+            # setup our at_exit callback is in the sinatra build callback honeybadger/init/sinatra.rb
             Honeybadger.install_at_exit_callback
             build_without_honeybadger(*args, &block)
           end

data/lib/honeybadger/logging.rb

@@ -4,13 +4,14 @@ require 'delegate'
 require 'forwardable'
 
 module Honeybadger
+  # @api private
   module Logging
     PREFIX = '** [Honeybadger] '.freeze
 
-    # Internal: Logging helper methods. Requires a Honeybadger::Config @config
-    # instance variable to exist and/or #logger to be defined. Each
-    # method is defined/block captured in this module rather than delegating to
-    # the logger directly to avoid extra object allocation.
+    # Logging helper methods. Requires a Honeybadger::Config @config instance
+    # variable to exist and/or #logger to be defined. Each method is
+    # defined/block captured in this module rather than delegating to the
+    # logger directly to avoid extra object allocation.
     module Helper
       private
       def debug(msg = nil)

data/lib/honeybadger/notice.rb

@@ -11,6 +11,7 @@ require 'honeybadger/util/request_hash'
 require 'honeybadger/util/request_payload'
 
 module Honeybadger
+  # @api private
   NOTIFIER = {
     name: 'honeybadger-ruby'.freeze,
     url: 'https://github.com/honeybadger-io/honeybadger-ruby'.freeze,
@@ -18,21 +19,27 @@ module Honeybadger
     language: 'ruby'.freeze
   }.freeze
 
-  # Internal: Substitution for gem root in backtrace lines.
+  # @api private
+  # Substitution for gem root in backtrace lines.
   GEM_ROOT = '[GEM_ROOT]'.freeze
 
-  # Internal: Substitution for project root in backtrace lines.
+  # @api private
+  # Substitution for project root in backtrace lines.
   PROJECT_ROOT = '[PROJECT_ROOT]'.freeze
 
-  # Internal: Empty String (used for equality comparisons and assignment).
+  # @api private
+  # Empty String (used for equality comparisons and assignment).
   STRING_EMPTY = ''.freeze
 
-  # Internal: A Regexp which matches non-blank characters.
+  # @api private
+  # A Regexp which matches non-blank characters.
   NOT_BLANK = /\S/.freeze
 
-  # Internal: Matches lines beginning with ./
+  # @api private
+  # Matches lines beginning with ./
   RELATIVE_ROOT = Regexp.new('^\.\/').freeze
 
+  # @api private
   MAX_EXCEPTION_CAUSES = 5
 
   class Notice
@@ -40,74 +47,79 @@ module Honeybadger
 
     include Conversions
 
-    # Internal: The String character used to split tag strings.
+    # @api private
+    # The String character used to split tag strings.
     TAG_SEPERATOR = ','.freeze
 
-    # Internal: The Regexp used to strip invalid characters from individual tags.
+    # @api private
+    # The Regexp used to strip invalid characters from individual tags.
     TAG_SANITIZER = /[^\w]/.freeze
 
-    # Public: The unique ID of this notice which can be used to reference the
-    # error in Honeybadger.
+    # The unique ID of this notice which can be used to reference the error in
+    # Honeybadger.
     attr_reader :id
 
-    # Public: The exception that caused this notice, if any.
+    # The exception that caused this notice, if any.
     attr_reader :exception
 
-    # Public: The exception cause if available.
+    # The exception cause if available.
     attr_reader :cause
 
-    # Public: The backtrace from the given exception or hash.
+    # The backtrace from the given exception or hash.
     attr_reader :backtrace
 
-    # Public: Custom fingerprint for error, used to group similar errors together.
+    # Custom fingerprint for error, used to group similar errors together.
     attr_reader :fingerprint
 
-    # Public: Tags which will be applied to error.
+    # Tags which will be applied to error.
     attr_reader :tags
 
-    # Public: The name of the class of error (example: RuntimeError).
+    # The name of the class of error (example: RuntimeError).
     attr_reader :error_class
 
-    # Public: The message from the exception, or a general description of the error.
+    # The message from the exception, or a general description of the error.
     attr_reader :error_message
 
     # Deprecated: Excerpt from source file.
     attr_reader :source
 
-    # Public: CGI variables such as HTTP_METHOD.
+    # CGI variables such as HTTP_METHOD.
     def cgi_data; @request[:cgi_data]; end
 
-    # Public: A hash of parameters from the query string or post body.
+    # A hash of parameters from the query string or post body.
     def params; @request[:params]; end
     alias_method :parameters, :params
 
-    # Public: The component (if any) which was used in this request (usually the controller).
+    # The component (if any) which was used in this request (usually the controller).
     def component; @request[:component]; end
     alias_method :controller, :component
 
-    # Public: The action (if any) that was called in this request.
+    # The action (if any) that was called in this request.
     def action; @request[:action]; end
 
-    # Public: A hash of session data from the request.
+    # A hash of session data from the request.
     def_delegator :@request, :session
     def session; @request[:session]; end
 
-    # Public: The URL at which the error occurred (if any).
+    # The URL at which the error occurred (if any).
     def url; @request[:url]; end
 
-    # Public: Local variables are extracted from first frame of backtrace.
+    # Local variables are extracted from first frame of backtrace.
     attr_reader :local_variables
 
-    # Public: The API key used to deliver this notice.
+    # The API key used to deliver this notice.
     attr_reader :api_key
 
-    # Internal: Cache project path substitutions for backtrace lines.
+    # @api private
+    # Cache project path substitutions for backtrace lines.
     PROJECT_ROOT_CACHE = {}
 
-    # Internal: Cache gem path substitutions for backtrace lines.
+    # @api private
+    # Cache gem path substitutions for backtrace lines.
     GEM_ROOT_CACHE = {}
 
-    # Internal: A list of backtrace filters to run all the time.
+    # @api private
+    # A list of backtrace filters to run all the time.
     BACKTRACE_FILTERS = [
       lambda { |line|
         return line unless defined?(Gem)
@@ -129,6 +141,7 @@ module Honeybadger
       lambda { |line| line if line !~ %r{lib/honeybadger} }
     ].freeze
 
+    # @api private
     def initialize(config, opts = {})
       @now = Time.now.utc
       @pid = Process.pid
@@ -170,9 +183,10 @@ module Honeybadger
       @fingerprint = construct_fingerprint(opts)
     end
 
-    # Internal: Template used to create JSON payload.
+    # @api private
+    # Template used to create JSON payload.
     #
-    # Returns Hash JSON representation of notice.
+    # @return [Hash] JSON representation of notice.
     def as_json(*args)
       @request[:context] = s(context)
       @request[:local_variables] = local_variables if local_variables
@@ -202,22 +216,21 @@ module Honeybadger
       }
     end
 
-    # Public: Creates JSON.
+    # Converts the notice to JSON.
     #
-    # Returns valid JSON representation of Notice.
+    # @return [Hash] The JSON representation of the notice.
     def to_json(*a)
       ::JSON.generate(as_json(*a))
     end
 
-    # Public: Allows properties to be accessed using a hash-like syntax.
-    #
-    # method - The given key for an attribute.
-    #
-    # Examples
+    # Allows properties to be accessed using a hash-like syntax.
     #
+    # @example
     #   notice[:error_message]
     #
-    # Returns the attribute value, or self if given `:request`.
+    # @param [Symbol] method The given key for an attribute.
+    #
+    # @return [Object] The attribute value.
     def [](method)
       case method
       when :request
@@ -227,7 +240,8 @@ module Honeybadger
       end
     end
 
-    # Internal: Determines if this notice should be ignored.
+    # @api private
+    # Determines if this notice should be ignored.
     def ignore?
       ignore_by_origin? || ignore_by_class? || ignore_by_callbacks?
     end
@@ -280,7 +294,7 @@ module Honeybadger
       end
     end
 
-    # Internal: Determines if error class should be ignored.
+    # Determines if error class should be ignored.
     #
     # ignored_class_name - The name of the ignored class. May be a
     # string or regexp (optional).
@@ -310,7 +324,7 @@ module Honeybadger
       Util::RequestHash.from_env(rack_env)
     end
 
-    # Internal: Construct the request object with data from various sources.
+    # Construct the request object with data from various sources.
     #
     # Returns Request.
     def construct_request_hash(config, opts)
@@ -324,7 +338,7 @@ module Honeybadger
       Util::RequestPayload.build(request)
     end
 
-    # Internal: Get optional context from exception.
+    # Get optional context from exception.
     #
     # Returns the Hash context.
     def exception_context(exception)
@@ -378,7 +392,7 @@ module Honeybadger
       Util::Sanitizer.sanitize(data)
     end
 
-    # Internal: Fetch local variables from first frame of backtrace.
+    # Fetch local variables from first frame of backtrace.
     #
     # exception - The Exception containing the bindings stack.
     #
@@ -412,14 +426,14 @@ module Honeybadger
       request_sanitizer.sanitize(result_hash)
     end
 
-    # Internal: Should local variables be sent?
+    # Should local variables be sent?
     #
     # Returns true to send local_variables.
     def send_local_variables?(config)
       config[:'exceptions.local_variables']
     end
 
-    # Internal: Parse Backtrace from exception backtrace.
+    # Parse Backtrace from exception backtrace.
     #
     # backtrace - The Array backtrace from exception.
     #
@@ -433,7 +447,7 @@ module Honeybadger
       )
     end
 
-    # Internal: Unwrap the exception so that original exception is ignored or
+    # Unwrap the exception so that original exception is ignored or
     # reported.
     #
     # exception - The exception which was rescued.
@@ -444,7 +458,7 @@ module Honeybadger
       exception_cause(exception) || exception
     end
 
-    # Internal: Fetch cause from exception.
+    # Fetch cause from exception.
     #
     # exception - Exception to fetch cause from.
     #
@@ -460,7 +474,7 @@ module Honeybadger
       end
     end
 
-    # Internal: Create a list of causes.
+    # Create a list of causes.
     #
     # cause - The first cause to unwrap.
     #
@@ -489,7 +503,7 @@ module Honeybadger
       rack_env && Array(rack_env['action_dispatch.parameter_filter']) or []
     end
 
-    # Internal: This is how much Honeybadger cares about Rails developers. :)
+    # This is how much Honeybadger cares about Rails developers. :)
     #
     # Some Rails projects include ActionDispatch::TestProcess globally for the
     # use of `fixture_file_upload` in tests. This is a bad practice because it
@@ -498,7 +512,7 @@ module Honeybadger
     #
     # When you call #session on any object which had previously defined it
     # (such as OpenStruct), that newly defined method calls #session on
-    # @request (defined in `ActionDispatch::TestProcess`), and if @request
+    # +@request+ (defined in `ActionDispatch::TestProcess`), and if +@request+
     # doesn't exist in that object, it calls #session *again* on `nil`, which
     # also inherited it from Object, resulting in a SystemStackError.
     #