kinetic_cafe_error 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be8bfda8e64ddea25cca49dd080dacfe1b489690
-  data.tar.gz: ada56cc846a9262dca8941335a32d290d29aa7ff
+  metadata.gz: 9f729db0dc8d7bd5d7299f904a9731348d5d22d0
+  data.tar.gz: 5f2cca7f8b42a6cfb4cc6cb45b6f4bc8602ac762
 SHA512:
-  metadata.gz: 811a51c61090c41d0ec80e7abf28fd3bdeb61852a8031d2c4159487d62562df9a81cf3f30ccfc0c3aa4e41be99f020ee03a6100ce26ef809ca8a1bfd03304dc6
-  data.tar.gz: 3ba9c1634d770fe886f268c085ddff9c941e5d1cd18b49f723ce71d20fd9bd7fe757825637f607e9aad72c4008aca011e614c16f7b9b88469938ff6e7ea2f0bb
+  metadata.gz: 2172f4681a2163199a49c1a099d84a50d6853db13db34e3462df7944239d8922c4e4e25c066ad170d8b82b4331d8ad9a33af00aae8da9b31a6b1e4449d84bb82
+  data.tar.gz: a134be803972f943ee5189ac97530f15c5bda8756b146d2c3996d4e89f99a9e72bd34733dc8bdc2a0860b1c92a78619d8064a4767d1859648d330dbbf8f0ea59

data/History.rdoc

@@ -1,3 +1,36 @@
+=== 1.2 / 2015-06-08
+
+* 1 major enhancement
+
+  * Changed the preferred way of creating an error hierarchy from just
+    extending the error class with KineticCafe::ErrorDSL to calling
+    KineticCafe.create_hierarchy. Among other options this provides, the
+    automatic creation of helper methods and errors based on Rack::Utils status
+    codes can be controlled.
+
+* 5 minor enhancements
+
+  * Renamed KineticCafe#header_only? to KineticCafe#header? The old version is
+    still present but deprecated. Similarly, the option to
+    KineticCafe::ErrorDSL#define_error is now called +header+, but
+    +header_only+ also works.
+
+  * Added an option, +i18n_params+ to KineticCafe::ErrorDSL#define_error, used
+    to describe the I18n parameters that are expected to be provided to the
+    error for translations. This gets defined as a class method on the new
+    error. This should be passed as an array.
+
+  * Extracted most of the 'magic' functionality to KineticCafe::ErrorModule so
+    that useful hierarchies can be generated without inheriting directly from
+    KineticCafe::Error.
+
+  * Added a class method to the Rails controller concern to generate a new
+    rescue_from for a non-KineticCafe::Error-derived exception.
+
+  * Added a pair of rake tasks, kcerror:defined (shows defined errors) and
+    kcerror:translations (generates a sample translation key file).
+    Automatically inserted for Rails applications.
+
 === 1.1 / 2015-06-05
 
 * 7 minor enhancements

data/Manifest.txt

@@ -26,8 +26,11 @@ lib/kinetic_cafe/error.rb
 lib/kinetic_cafe/error/minitest.rb
 lib/kinetic_cafe/error_dsl.rb
 lib/kinetic_cafe/error_engine.rb
+lib/kinetic_cafe/error_module.rb
 lib/kinetic_cafe/error_rspec.rb
+lib/kinetic_cafe/error_tasks.rake
 lib/kinetic_cafe_error.rb
 test/test_helper.rb
 test/test_kinetic_cafe_error.rb
 test/test_kinetic_cafe_error_dsl.rb
+test/test_kinetic_cafe_error_hierarchy.rb

data/README.rdoc

@@ -9,24 +9,111 @@ continuous integration :: {<img src="https://travis-ci.org/KineticCafe/kinetic_c
 kinetic_cafe_error provides an API-smart error base class and a DSL for
 defining errors. Under Rails, it also provides a controller concern
 (KineticCafe::ErrorHandler) that has a useful implementation of +rescue_from+
-for KineticCafe::Error types.
+to handle KineticCafe::Error types.
+
+Exceptions in a hierarchy can be handled in a uniform manner, including getting
+an I18n translation message with parameters, standard status values, and
+meaningful JSON representations that can be used to establish a standard error
+representations across both clients and servers.
 
 == Synopsis
 
-  class MyErrorBase < KineticCafe::Error
-    extend KineticCafe::ErrorDSL
-  
-    not_found class: :user # => MyErrorBase::UserNotFound
-    unauthorized class: :user # => MyErrorBase::UserUnauthorized
-    forbidden class: :user # => MyErrorBase::UserForbidden
-    conflict class: :user# => MyErrorBase::UserConflict
+Define a hierarchy with KineticCafe::Error.hierarchy.
+
+  KineticCafe::Error.hierarchy class: :MyBaseError do
+    not_found class: :user # => MyBaseError::UserNotFound
+    unauthorized class: :user # => MyBaseError::UserUnauthorized
+    forbidden class: :user # => MyBaseError::UserForbidden
+    conflict class: :user# => MyBaseError::UserConflict
   end
 
+There are a few documented ways to define hierarchies. Examples for handling
+exceptions can be found in the provided Minitest assertions module and the
+RSpec matchers.
+
+=== Using with Rails
+
+When using KineticCafe::Error with Rails, KineticCafe::ErrorEngine is
+automatically injected, which enables the following functionality:
+
+* Two rake tasks:
+
+  * <tt>rake kcerror:defined</tt>, showing the errors defined in the known
+    hierarchy.
+
+  * <tt>rake kcerror:translations[output]</tt>, creating a template translation
+    file for all defined errors.
+
+* An error view, <tt>kinetic_cafe_error/page</tt>, in ERB, HAML, and Slim
+  formats. This also has a partial, <tt>kinetic_cafe_error/_table</tt>. This
+  allows KineticCafe::Error classes to be used in HTML contexts as well as JSON
+  contexts.
+
+* Access to the kinetic_cafe_error translation files for English and French,
+  used in logging and in the error view.
+
+* A controller concern, KineticCafe::ErrorHandler, that defines a +rescue_from+
+  handler for descendants of the KineticCafe::Error class, and a error handler
+  generator, #kinetic_cafe_error_handler_for, that sets a +rescue_from+ handler
+  for a KineticCafe::Error hierarchy that does not descend from
+  KineticCafe::Error itself.
+
+  #kinetic_cafe_error_handler distinguishes between HTML and JSON contexts.
+
+=== Using with Minitest
+
+KineticCafe::Error provides a number of assertions that can help testing that
+your code returns KineticCafe::Error hierarchies.
+
+* #assert_kc_error when used with the return value of +assert_raises+, verifies
+  that the captured exception is the expected exception, including parameters.
+  Also available as #must_be_kc_error.
+
+* assert_kc_error_json when used with a response body, verifies that the
+  response is the same as would be generated with the requested error class.
+  Also available as #must_be_kc_error_json.
+
+* assert_response_kc_error_html works with ActiveSupport::Test; it asserts that
+  the +kinetic_cafe_error/page+ template has been rendered and that the
+  expected class I18n key is part of the response body. Depends on
+  <tt>@response.body</tt> being part of the available test environment.
+
+* assert_response_kc_Error works with ActiveSupport::Test and checks
+  <tt>@request.format</tt> to determine whether to forward to
+  #assert_response_kc_error_html or #assert_kc_error_json.
+
+Get access to these with:
+
+  require 'kinetic_cafe/error/minitest'
+
+In your test setup code.
+
+=== Using with RSpec (Experimental)
+
+KineticCafe::Error provides four experimental matchers:
+
+* +be_json_for+ verifies that the JSON in the +actual+ string or body match the
+  +expected+ data structure.
+* +be_kc_error+ verifies that the error is the expected class and renders
+  properly with the same parameters.
+* +be_kc_error_json+ verifies that the JSON provided that the JSON output of the
+  +expected+ is generates the same JSON.
+* +be_kc_error_html+ verifies that the response renders the
+  +kinetic_cafe_error/page+ template.
+
 == Install
 
-Add kinetic_cafe_error to your gemfile:
+Add kinetic_cafe_error to your Gemfile:
+
+  gem 'kinetic_cafe_error', '~> 1.2'
+
+If not using Rails, install with RubyGems:
+
+  gem install kinetic_cafe_error
+
+And require where needed in your application:
 
-  gem 'kinetic_cafe_error', '~> 1.0'
+  require 'kinetic_cafe_error'
 
 :include: Contributing.rdoc
 :include: Licence.rdoc

data/Rakefile

@@ -64,4 +64,6 @@ namespace :test do
   end
 end
 
+load 'lib/kinetic_cafe/error_tasks.rake'
+
 # vim: syntax=ruby

data/app/controllers/concerns/kinetic_cafe/error_handler.rb

@@ -7,7 +7,16 @@ module KineticCafe::ErrorHandler
   extend ActiveSupport::Concern
 
   included do
-    rescue_from KineticCafe::Error, with: :kinetic_cafe_error_handler
+    kinetic_cafe_error_handler_for KineticCafe::Error
+  end
+
+  module ClassMethods
+    # Create a new +rescue_from+ handler for the specified base class. Useful
+    # if the base is not a descendant of KineticCafe::Error, but includes
+    # KineticCafe::ErrorHandler.
+    def kinetic_cafe_error_handler_for(klass)
+      rescue_from klass, with: :kinetic_cafe_error_handler
+    end
   end
 
   # This method is called with +error+ when Rails catches a KineticCafe::Error
@@ -19,7 +28,9 @@ module KineticCafe::ErrorHandler
   # controllers for different behaviour.
   def kinetic_cafe_error_handler(error)
     Rails.logger.error(error.message)
-    Rails.logger.error("^-- caused by: #{error.cause.message}") if error.cause
+    if error.cause
+      Rails.logger.error(t('kinetic_cafe_error.cause', error.cause.message))
+    end
 
     respond_to do |format|
       format.html do

data/config/locales/kinetic_cafe_error.en-CA.yml

@@ -12,3 +12,5 @@ en-CA:
       header:
         status: Status
         code: Code
+    cause: >-
+      ^-- caused by: %{message}

data/config/locales/kinetic_cafe_error.en-UK.yml

@@ -12,3 +12,5 @@ en-UK:
       header:
         status: Status
         code: Code
+    cause: >-
+      ^-- caused by: %{message}

data/config/locales/kinetic_cafe_error.en-US.yml

@@ -12,3 +12,5 @@ en-US:
       header:
         status: Status
         code: Code
+    cause: >-
+      ^-- caused by: %{message}

data/config/locales/kinetic_cafe_error.en.yml

@@ -12,3 +12,5 @@ en:
       header:
         status: Status
         code: Code
+    cause: >-
+      ^-- caused by: %{message}

data/config/locales/kinetic_cafe_error.fr-CA.yml

@@ -12,3 +12,5 @@ fr-CA:
       header:
         status: Condition
         code: Code
+    cause: >-
+      ^-- causé par: %{message}

data/config/locales/kinetic_cafe_error.fr.yml

@@ -12,3 +12,5 @@ fr:
       header:
         status: Condition
         code: Code
+    cause: >-
+      ^-- causé par: %{message}

data/lib/kinetic_cafe/error.rb

@@ -1,4 +1,6 @@
-module KineticCafe #:nodoc:
+require_relative 'error_module'
+
+module KineticCafe # :nodoc:
   # A subclass of StandardError that can render itself as a descriptive JSON
   # hash, or as a hash that can be passed to a Rails controller +render+
   # method.
@@ -9,12 +11,10 @@ module KineticCafe #:nodoc:
   #
   # == Defining an Error Hierarchy
   #
-  # An error hierarchy is defined by subclassing KineticCafe::Error, extending
-  # it with KineticCafe::ErrorDSL, and defining error subclasses with the DSL.
-  #
-  #   class MyErrorBase < KineticCafe::Error
-  #     extend KineticCafe::ErrorDSL
+  # An error hierarchy is defined by using KineticCafe::Error.hierarchy and
+  # defining error subclasses with the DSL.
   #
+  #   KineticCafe::Error.hierarchy(class: :MyErrorBase) do
   #     not_found class: :user # => MyErrorBase::UserNotFound
   #     unauthorized class: :user # => MyErrorBase::UserUnauthorized
   #     forbidden class: :user # => MyErrorBase::UserForbidden
@@ -25,147 +25,148 @@ module KineticCafe #:nodoc:
   # rescue clause and handled there, as is shown in the included
   # KineticCafe::ErrorHandler controller concern for Rails.
   class Error < ::StandardError
-    VERSION = '1.1' # :nodoc:
+    VERSION = '1.2' # :nodoc:
 
-    # The HTTP status to be returned. If not provided in the constructor, uses
-    # #default_status.
-    attr_reader :status
-    # Extra data relevant to recipients of the exception, provided on
-    # construction.
-    attr_reader :extra
-    # The exception that caused this exception; provided on construction.
-    attr_reader :cause
+    # Get the KineticCafe::Error functionality.
+    include KineticCafe::ErrorModule
 
-    # Create a new error with the given parameters.
+    # Create an error hierarchy using +options+ and the optional +block+. When
+    # given, the +block+ will either +yield+ the hierarchy base (if the block
+    # accepts arguments) or run with +instance_eval+.
+    #
+    # If the class does not already include KineticCafe::ErrorModule, it will
+    # be included.
+    #
+    # === Building a Hierarchy
+    #
+    # A hierarchy using KineticCafe::Error as its base can be created with
+    # KineticCafe::Error.hierarchy and no arguments.
+    #
+    #   KineticCafe::Error.hierarchy do
+    #     not_found class: :user # => KineticCafe::Error::UserNotFound
+    #   end
+    #
+    # A hierarchy in a new error class (that descends from KineticCafe::Error)
+    # can be created by providing a class name:
+    #
+    #   KineticCafe::Error.hierarchy(class: :MyErrorBase) do
+    #     not_found class: :user # => MyErrorBase::UserNotFound
+    #   end
+    #
+    # The new error class can itself be in a namespace, but the parent
+    # namespace must be identified:
+    #
+    #   module My; end
+    #
+    #   KineticCafe::Error.hierarchy(class: :ErrorBase, namespace: My) do
+    #     not_found class: :user # => My::ErrorBase::UserNotFound
+    #   end
+    #
+    # It is also possible to use an explicit descendant easily:
+    #
+    #   module My
+    #     ErrorBase = Class.new(KineticCafe::Error)
+    #   end
+    #
+    #   KineticCafe::Error.hierarchy(class: My::ErrorBase) do
+    #     not_found class: :user # => My::ErrorBase::UserNotFound
+    #   end
+    #
+    # === Rack::Utils Errors and Helpers
+    #
+    # By default, when Rack::Utils is present, KineticCafe::Error will present
+    # helper methods and default HTTP status code errors.
+    #
+    #   KineticCafe::Error.hierarchy do
+    #     not_found class: :user # => KineticCafe::Error::UserNotFound
+    #   end
+    #
+    #   KineticCafe::Error::UserNotFound.new.status # => :not_found / 404
+    #   KineticCafe::Error::NotFound.new.status #  => :not_found
+    #
+    # These may be controlled with the option +rack_status+. If provided as
+    # +false+, neither will be created:
+    #
+    #   KineticCafe::Error.hierarchy(rack_status: false) do
+    #     not_found class: :user # => raises NoMethodError
+    #   end
+    #
+    #   fail KineticCafe::Error::NotFound # => raises NameError
+    #
+    # These may be controlled individually, as well. Disable the methods:
+    #
+    #   KineticCafe::Error.hierarchy(rack_status: { methods: false }) do
+    #     not_found class: :user # => raises NoMethodError
+    #   end
+    #
+    #   fail KineticCafe::Error::NotFound # => works
+    #
+    # Disable the default error classes:
+    #
+    #   KineticCafe::Error.hierarchy(rack_status: { errors: false }) do
+    #     not_found class: :user # => KineticCafe::Error::UserNotFound
+    #   end
+    #
+    #   fail KineticCafe::Error::NotFound # => raises NoMethodError
     #
     # === Options
     #
-    # +message+:: A message override. This may be provided either as the first
-    #             parameter to the constructor or may be provided as an option.
-    #             A value provided as the first parameter overrides any other
-    #             value.
-    # +status+::  An override to the HTTP status code to be returned by this
-    #             error by default.
-    # +i18n_params+:: The parameters to be sent to I18n.translate with the
-    #                 #i18n_key.
-    # +cause+:: The exception that caused this error. Used to wrap an earlier
-    #           exception.
-    # +extra+:: Extra data to be returned in the API representation of this
-    #           exception.
-    # +query+:: A hash of parameters, typically from Rails controller +params+
-    #           or model +where+ query. This hash will be converted into a
-    #           string value similar to ActiveSupport#to_query.
-    #
-    # Any unmatched options will be added transparently to +i18n_params+.
-    # Because of this, the following constructors are identical:
-    #
-    #     KineticCafe::Error.new(i18n_params: { x: 1 })
-    #     KineticCafe::Error.new(x: 1)
-    #
-    # :call-seq:
-    #    new(message, options = {})
-    #    new(options)
-    def initialize(*args)
-      options = args.last.kind_of?(Hash) ? args.pop.dup : {}
-      @message = args.shift
-      @message = options.delete(:message) if @message.nil? || @message.empty?
-      options.delete(:message)
-
-      @message && @message.freeze
-
-      @status      = options.delete(:status) || default_status
-      @i18n_params = options.delete(:i18n_params) || {}
-      @extra       = options.delete(:extra)
-      @cause       = options.delete(:cause)
-
-      @i18n_params.update(cause: cause.message) if cause
-
-      query = options.delete(:query)
-      @i18n_params.merge!(query: stringify(query)) if query
-      @i18n_params.merge!(options)
-      @i18n_params.freeze
-    end
-
-    # The message associated with this exception. If not provided, defaults to
-    # #i18n_message.
-    def message
-      @message || i18n_message
-    end
-
-    # The name of the error class.
-    def name
-      @name ||= KineticCafe::ErrorDSL.namify(self.class.name)
-    end
-
-    # The key used for I18n translation.
-    def i18n_key
-      @i18n_key ||= "#{self.class.i18n_key_base}.#{name}".freeze
-    end
-    alias_method :code, :i18n_key
+    # +class+:: If given, identifies the base class and host namespace of the
+    #           error hierarchy. Provided as a class, that class is used.
+    #           Provided as a symbol, creates a new class that descends from
+    #           KineticCafe::Error.
+    # +namespace+:: If +class+ is provided as a symbol, this namespace will be
+    #               the one where the new error class is created.
+    # +rack_status+:: Controls the creation of error-definition helper methods
+    #                 and errors based on Rack::Utils status codes (e.g.,
+    #                 +not_found+). +true+ creates both; +false+ disables both.
+    #                 The values <tt>{ methods: false }</tt> and <tt>{ errors:
+    #                 false }</tt> individually control one.
+    def self.hierarchy(options = {}, &block) # :yields base:
+      base = options.fetch(:class, self)
+
+      if base.kind_of?(Symbol)
+        ns = options.fetch(:namespace, Object)
+        base = if ns.const_defined?(base)
+                 ns.const_get(base)
+               else
+                 ns.const_set(base, Class.new(self))
+               end
+      end
 
-    # Indicates that this error should *not* have its details rendered to the
-    # user, but should use the +head+ method.
-    def header_only?
-      false
-    end
+      if base.singleton_class < KineticCafe::ErrorDSL
+        fail "#{base} is already a root hierarchy"
+      end
 
-    # Indicates that this error should be rendered to the client, but clients
-    # are advised *not* to display the message to the user.
-    def internal?
-      false
-    end
+      unless base <= ::StandardError
+        fail "#{base} cannot root a hierarchy (not a StandardError)"
+      end
 
-    # The I18n translation of the message. If I18n.translate is defined,
-    # returns #i18n_key and the I18n parameters.
-    def i18n_message
-      @i18n_message ||= if defined?(I18n.translate)
-                          I18n.translate(i18n_key, @i18n_params).freeze
-                        else
-                          [ i18n_key, @i18n_params ].freeze
-                        end
-    end
+      unless base <= KineticCafe::ErrorModule
+        base.send(:include, KineticCafe::ErrorModule)
+      end
 
-    # The details of this error as a hash. Values that are empty or nil are
-    # omitted.
-    def api_error(*)
-      {
-        message:      @message,
-        status:       status,
-        name:         name,
-        internal:     internal?,
-        i18n_message: i18n_message,
-        i18n_key:     i18n_key,
-        i18n_params:  @i18n_params,
-        cause:        cause && cause.message,
-        extra:        extra
-      }.delete_if { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
-    end
-    alias_method :as_json, :api_error
+      unless rs_defined = base.respond_to?(:__rack_status)
+        base.send :define_singleton_method, :__rack_status do
+          options.fetch(:rack_status, { errors: true, methods: true })
+        end
+      end
 
-    # An error result that can be passed as a response body.
-    def error_result
-      { error: api_error, message: message }
-    end
+      base.send(:extend, KineticCafe::ErrorDSL)
 
-    # A hash that can be passed to the Rails +render+ method with +status+ of
-    # #status and +layout+ false. The +json+ field is rendered as a hash of
-    # +error+ (calling #api_error) and +message+ (calling #message).
-    def json_result
-      { status: status, json: error_result, layout: false }
-    end
-    alias_method :render_json_for_rails, :json_result
-
-    # Nice debugging version of a KineticCafe::Error
-    def inspect
-      "#<#{self.class}: name=#{name} status=#{status} " \
-        "message=#{message.inspect} i18n_key=#{i18n_key} " \
-        "i18n_params=#{@i18n_params.inspect} extra=#{extra.inspect} " \
-        "cause=#{cause}>"
-    end
+      if block_given?
+        if block.arity > 0
+          yield base
+        else
+          base.instance_eval(&block)
+        end
+      end
 
-    # The base for I18n key resolution.
-    def self.i18n_key_base
-      'kcerrors'.freeze
+      base
+    ensure
+      if base.respond_to?(:__rack_status) && !rs_defined
+        base.singleton_class.send :undef_method, :__rack_status
+      end
     end
 
     private