kinetic_cafe_error 1.1 → 1.2

data/lib/kinetic_cafe/error/minitest.rb

@@ -7,6 +7,9 @@ module Minitest #:nodoc:
     def assert_kc_error expected, actual, params = {}, msg = nil
       msg, params = params, {} if msg.nil? && params.kind_of?(String)
 
+      assert_kind_of KineticCafe::ErrorDSL, actual,
+        msg || "Expected #{actual} to be #{expected}, but it was not."
+
       assert_kind_of expected, actual,
         msg || "Expected #{actual} to be #{expected}, but it was not."
 
@@ -34,14 +37,36 @@ module Minitest #:nodoc:
     end
 
     # Assert that a reponse body (<tt>@response.body</tt>, useful from
-    # ActionController::TestCase) is JSON for the expected error. This is a
+    # ActionController::TestCase) is HTML for the expected error.
     # convenience wrapper around #assert_kc_error_json.
+    def assert_response_kc_error_html expected, params = {}, msg = nil
+      msg, params = params, {} if msg.nil? && params.kind_of?(String)
+
+      msg ||= "Expected #{actual} to be HTML for #{expected}, but it was not."
+
+      assert_template 'kinetic_cafe_error/page', msg
+      assert_template 'kinetic_cafe_error/_table', msg
+
+      assert_match(/#{expected.i18n_key}/, @response.body, msg)
+      assert_response expected.new.status, msg
+    end
+
+    # Assert that a reponse body (<tt>@response.body</tt>, useful from
+    # ActionController::TestCase) is JSON for the expected error. This is a
+    # convenience wrapper around #assert_kc_error_json or
+    # #assert_kc_error_html, depending on whether or not the response is HTML
+    # or not.
     def assert_response_kc_error expected, params = {}, msg = nil
       if msg.nil? && params.kind_of?(String)
         msg, params = params, {}
       end
       msg ||= "Expected response to be #{expected}, but was not."
-      assert_kc_error_json expected, @response.body, params, msg
+
+      if @request.format.html?
+        assert_response_kc_error_html expected, params, msg
+      else
+        assert_kc_error_json expected, @response.body, params, msg
+      end
     end
 
     Minitest::Test.send(:include, self)

data/lib/kinetic_cafe/error_dsl.rb

@@ -66,22 +66,26 @@ module KineticCafe
     #              define_error class: :object, status: :not_found
     #
     #            will create an +ObjectNotFound+ error class.
-    #
-    # +header_only+:: Indicates that when this is caught, it should not be
-    #                 returned with full details, but shoudl instead be treated
-    #                 as a header-only API response.
+    # +header+:: Indicates that when this is caught, it should not be returned
+    #            with full details, but should instead be treated as a
+    #            header-only API response. Also available as +header_only+.
+    # +internal+:: Generates a response that indicates to clients that the
+    #              error should not be shown to users.
+    # +i18n_params+:: An array of parameter names that are expected to be
+    #                 provided for translation. This helps document the
+    #                 expected translations.
     def define_error(options)
       fail ArgumentError, 'invalid options' unless options.kind_of?(Hash)
       fail ArgumentError, 'define what error?' if options.empty?
 
       options = options.dup
+      status = options[:status]
 
       klass = options.delete(:class)
       if klass
         if options.key?(:key)
           fail ArgumentError, ":key conflicts with class:#{klass}"
         end
-        status = options[:status]
 
         key = if status.kind_of?(Symbol) or status.kind_of?(String)
                 "#{klass}_#{KineticCafe::ErrorDSL.namify(status)}"
@@ -89,8 +93,7 @@ module KineticCafe
                 "#{klass}_#{KineticCafe::ErrorDSL.namify(self.name)}"
               end
       else
-        status = options[:status]
-        key    = options.fetch(:key) {
+        key = options.fetch(:key) {
           fail ArgumentError, 'one of :key or :class must be provided'
         }.to_s
       end
@@ -116,13 +119,19 @@ module KineticCafe
       error = Class.new(self)
       error.send :define_method, :name, -> { key }
       error.send :define_method, :i18n_key, -> { i18n_key }
+      error.send :define_singleton_method, :i18n_key, -> { i18n_key }
 
-      if options[:header_only]
-        error.send :define_method, :header_only?, -> { true }
+      if options[:header] || options[:header_only]
+        error.send :define_method, :header?, -> { true }
+        error.send :alias_method, :header_only?, :header?
       end
 
-      if options[:internal]
-        error.send :define_method, :internal?, -> { true }
+      error.send :define_method, :internal?, -> { true } if options[:internal]
+
+      i18n_params = options[:i18n_params]
+      if i18n_params || !error.respond_to?(:i18n_params)
+        i18n_params = Array(i18n_params).freeze
+        error.send :define_singleton_method, :i18n_params, -> { i18n_params }
       end
 
       status ||= defined?(Rack::Utils) && :bad_request || 400
@@ -134,10 +143,6 @@ module KineticCafe
       const_set(error_name, error)
     end
 
-    ##
-    # 
-
-
     private
 
     ##
@@ -151,13 +156,28 @@ module KineticCafe
         fail "#{self} cannot extend #{base} (not a StandardError)"
       end
 
-      if defined?(Rack::Utils)
+      rack_status = base.__rack_status if base.respond_to?(:__rack_status)
+
+      case rack_status
+      when Hash
+        rack_status = { methods: true, errors: true }.merge(rack_status)
+      when true, nil
+        rack_status = {}.freeze
+      when false
+        rack_status = { methods: false, errors: false }.freeze
+      end
+
+      if defined?(Rack::Utils) && rack_status
         Rack::Utils::SYMBOL_TO_STATUS_CODE.each do |name, value|
-          base.singleton_class.send :define_method, name do |options = {}|
-            define_error(options.merge(status: name))
+          if rack_status.fetch(:methods, true)
+            base.singleton_class.send :define_method, name do |options = {}|
+              define_error(options.merge(status: name))
+            end
           end
 
-          base.send :define_error, status: name, key: name
+          if rack_status.fetch(:errors, true)
+            base.send :define_error, status: name, key: name
+          end
         end
       end
     end

data/lib/kinetic_cafe/error_engine.rb

@@ -2,5 +2,8 @@ module KineticCafe
   # If Rails is defined, KineticCafe::ErrorEngine will be loaded automatically,
   # providing access to the KineticCafe::ErrorHandler.
   class ErrorEngine < ::Rails::Engine
+    rake_tasks do
+      load "#{__dir__}/error_tasks.rake"
+    end
   end
 end

data/lib/kinetic_cafe/error_module.rb

@@ -0,0 +1,192 @@
+module KineticCafe # :nodoc:
+  # The core functionality provided by a KineticCafe::Error, extracted to a
+  # module to ensure that exceptions that are made hosts of error hierarchies
+  # have expected functionality.
+  module ErrorModule
+    # 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
+
+    # Create a new error with the given parameters.
+    #
+    # === 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 added to +i18n_params+, 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 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 ||= if self.class.respond_to? :i18n_key
+                      self.class.i18n_key
+                    else
+                      [
+                        i18n_key_base, (name)
+                      ].join('.').freeze
+                    end
+    end
+    alias_method :code, :i18n_key
+
+    # Indicates that this error should *not* have its details rendered to the
+    # user, but should use the +head+ method.
+    def header?
+      false
+    end
+    alias_method :header_only?, :header?
+
+    # 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
+
+    # 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
+
+    # 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
+
+    # An error result that can be passed as a response body.
+    def error_result
+      { error: api_error, message: message }
+    end
+
+    # 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
+
+    class << self
+      ##
+      # The base for I18n key resolution. Defaults to 'kcerrors'.
+      #
+      # :method: i18n_key_base
+
+      ##
+      # The names of the expected parameters for this error. Defaults to [].
+      #
+      # :method: i18n_params
+
+      ##
+      # The i18n_key for the parameter. Defaults to the combination of
+      # i18n_key_base and the namified version of the class (see
+      # KineticCafe::ErrorDSL.namify).
+      #
+      # :method: i18n_key
+
+      ##
+      def included(mod)
+        unless mod.respond_to?(:i18n_key_base)
+          mod.send :define_singleton_method, :i18n_key_base do
+            'kcerrors'.freeze
+          end
+        end
+
+        unless mod.respond_to?(:i18n_params)
+          mod.send :define_singleton_method, :i18n_params do
+            [].freeze
+          end
+        end
+
+        unless mod.respond_to?(:i18n_key)
+          mod.send :define_singleton_method, :i18n_key do
+            @i18n_key ||= [
+              i18n_key_base, KineticCafe::ErrorDSL.namify(name)
+            ].join('.').freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kinetic_cafe/error_rspec.rb

@@ -12,6 +12,14 @@ module KineticCafe
   # +be_json_for+:: Verifies that the expected value is a JSON representation
   #                 of the actual value. If the actual value responds to
   #                 #body, the actual value is replaced with +actual.body+.
+  #
+  # +be_kc_error+:: Verifies that the expected value is a KineticCafe::Error.
+  #
+  # +be_kc_error_json+:: Verifies that the JSON value matches the output of
+  #                      KineticCafe::Error.
+  #
+  # +be_kc_error_html+:: Verifies that the rendered HTML matches the output of
+  #                      KineticCafe::Error.
   module ErrorRspec
     extend ::Rspec::Matchers::DSL
 
@@ -30,6 +38,7 @@ module KineticCafe
 
     matcher :be_kc_error do |expected, params = {}|
       match do |actual|
+        expect(actual).to be_kind_of(KineticCafe::ErrorModule)
         expect(actual).to be_kind_of(expected)
         expect(actual).to eq(expected.new(params))
       end
@@ -45,5 +54,13 @@ module KineticCafe
 
       diffable
     end
+
+    matcher :be_kc_error_html do |expected, params = {}|
+      match do |actual|
+        expect(actual).to render_template('kinetic_cafe_error/page')
+        expect(actual).to render_template('kinetic_cafe_error/_table')
+        expect(actual).to include(expected.i18n_key)
+      end
+    end
   end
 end

data/lib/kinetic_cafe/error_tasks.rake

@@ -0,0 +1,59 @@
+namespace :kcerror do
+  desc 'Show defined errors.'
+  task defined: 'kcerror:find' do
+    display = ->(root, prefix = '') {
+      puts "#{prefix}- #{root}"
+
+      if @descendants[root]
+        sorted = @descendants[root].sort_by(&:to_s)
+        sorted.each do |child|
+          s = (child == sorted.last) ? '`' : '|'
+          display.(child, "#{prefix.tr('|`', ' ')}  #{s}")
+        end
+      end
+    }
+
+    @descendants[StandardError].sort_by(&:to_s).each { |d| display.(d) }
+  end
+
+  desc 'Generate a sample translation key file.'
+  task :translations, [ :output ] => 'kcerror:find' do |_, args|
+    translations = {}
+    traverse = ->(root) {
+      translation = (translations[root.i18n_key_base] ||= {})
+      name = KineticCafe::ErrorDSL.namify(root)
+
+      params = root.i18n_params.map { |param| "%{#{param}}" }.join(' ')
+
+      if params.empty?
+        translation[name] = %Q(Translation for #{name} with no params.)
+      else
+        translation[name] = %Q(Translation for #{name} with #{params}.)
+      end
+
+      if @descendants[root]
+        @descendants[root].sort_by(&:to_s).each { |child| traverse.(child) }
+      end
+    }
+
+    @descendants[StandardError].sort_by(&:to_s).each { |d| traverse.(d) }
+
+    require 'yaml'
+    translations = YAML.dump({ 'en' => translations })
+
+    if args.output
+      File.open(args.output, 'w') { |f| f.write translations }
+    else
+      puts translations
+    end
+  end
+
+  task :find do
+    @descendants = {}
+    ObjectSpace.each_object(Class) do |k|
+      next unless k.singleton_class < KineticCafe::ErrorDSL
+
+      (@descendants[k.superclass] ||= []) << k
+    end
+  end
+end