kinetic_cafe_error 1.0

data/config/locales/kinetic_cafe_error.en_us.yml

@@ -0,0 +1,21 @@
+en-US:
+  kinetic_cafe_error:
+    page:
+      title: >-
+        An error occurred.
+      body_html: |
+        <p>The person responsible has been informed.</p>
+        <p>I’m not allowed to say anything else.</p>
+        <p>…</p>
+        <p>OK. Just for you, here’s a bit more:</p>
+      error_table_html: |
+        <table>
+          <tbody>
+            <tr>
+              <th>Status</th><td>&nbsp;</td><td>%{status}</td>
+            </tr>
+            <tr>
+              <th>Code</th><td>&nbsp;</td><td>%{code}</td>
+            </tr>
+          </tbody>
+        </table>

data/config/locales/kinetic_cafe_error.fr.yml

@@ -0,0 +1,21 @@
+fr-CA:
+  kinetic_cafe_error:
+    page:
+      title: >-
+        Il y avait une erreur.
+      body_html: |
+        <p>La personne qui a causé il a été informé.</p>
+        <p>Je ne suis pas autorisé à dire quoi que ce soit d’autre à ce sujet.</p>
+        <p>…</p>
+        <p>D’ACCORD. Juste pour vous, voici un peu plus:</p>
+      error_table_html: |
+        <table>
+          <tbody>
+            <tr>
+              <th>Condition</th><td>&nbsp;</td><td>%{status}</td>
+            </tr>
+            <tr>
+              <th>Code</th><td>&nbsp;</td><td>%{code}</td>
+            </tr>
+          </tbody>
+        </table>

data/config/locales/kinetic_cafe_error.fr_ca.yml

@@ -0,0 +1,21 @@
+fr-CA:
+  kinetic_cafe_error:
+    page:
+      title: >-
+        Il y avait une erreur.
+      body_html: |
+        <p>La personne qui a causé il a été informé.</p>
+        <p>Je ne suis pas autorisé à dire quoi que ce soit d’autre à ce sujet.</p>
+        <p>…</p>
+        <p>D’ACCORD. Juste pour vous, voici un peu plus:</p>
+      error_table_html: |
+        <table>
+          <tbody>
+            <tr>
+              <th>Condition</th><td>&nbsp;</td><td>%{status}</td>
+            </tr>
+            <tr>
+              <th>Code</th><td>&nbsp;</td><td>%{code}</td>
+            </tr>
+          </tbody>
+        </table>

data/lib/kinetic_cafe/error.rb

@@ -0,0 +1,217 @@
+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.
+  #
+  # This class is not expected to be used on its own, but is used as the parent
+  # (both in terms of base class and namespace) of an application error
+  # hierarchy.
+  #
+  # == 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
+  #
+  #     not_found class: :user # => MyErrorBase::UserNotFound
+  #     unauthorized class: :user # => MyErrorBase::UserUnauthorized
+  #     forbidden class: :user # => MyErrorBase::UserForbidden
+  #     conflict class: :user# => MyErrorBase::UserConflict
+  #   end
+  #
+  # These errors then can be used and caught with a generic KineticCafe::Error
+  # rescue clause and handled there, as is shown in the included
+  # KineticCafe::ErrorHandler controller concern for Rails.
+  class Error < ::StandardError
+    VERSION = '1.0' # :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
+
+    # 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, 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
+
+    # Indicates that this error should *not* have its details rendered to the
+    # user, but should use the +head+ method.
+    def header_only?
+      false
+    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
+
+    # 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
+
+    # The base for I18n key resolution.
+    def self.i18n_key_base
+      'kcerrors'.freeze
+    end
+
+    private
+
+    def default_status
+      defined?(Rack::Utils) && :bad_request || 400
+    end
+
+    def stringify(object, namespace = nil)
+      case object
+      when Hash
+        stringify_hash(object, namespace).compact.sort.join('; ')
+      when Array
+        stringify_array(object, namespace)
+      else
+        stringify_value(namespace, object)
+      end
+    end
+
+    def stringify_hash(hash, namespace)
+      hash.collect do |key, value|
+        key = namespace ? "#{namespace}[#{key}]" : key
+        case value
+        when Hash
+          next if value.nil?
+          stringify(value, key)
+        when Array
+          stringify_array(key, value)
+        else
+          stringify_value(key, value)
+        end
+      end
+    end
+
+    def stringify_array(key, array)
+      key = "#{key}[]"
+      if array.empty?
+        stringify_value(key, [])
+      else
+        array.collect { |value| stringify(value, key) }.join(', ')
+      end
+    end
+
+    def stringify_value(key, value)
+      "#{key}: #{value}"
+    end
+  end
+end
+
+require_relative 'error_dsl'

data/lib/kinetic_cafe/error_dsl.rb

@@ -0,0 +1,165 @@
+module KineticCafe
+  # Make defining new children of KineticCafe::Error easy. Adds the
+  # #define_error method.
+  #
+  # If using when Rack is present, useful variant methodss are provided
+  # matching Rack status symbol codes. These set the default status to the Rack
+  # status.
+  #
+  #    conflict class: :user # => UserConflict, status: :conflict
+  #    not_found class: :post # => PostNotFound, status: :not_found
+  module ErrorDSL
+    # Convert ThisName to this_name. Uses #underscore if +name+ responds to it.
+    # Otherwise, it uses a super naïve version.
+    def self.underscore(name)
+      name = name.to_s
+      if name.respond_to?(:underscore)
+        name.underscore.freeze
+      else
+        name.dup.tap { |n|
+          n.gsub!(/[[:upper:]]/) { "_#$&".downcase }
+          n.sub!(/^_/, '')
+        }.freeze
+      end
+    end
+
+    # Demodulizes This::Name to just Name. Uses name#demodulize if it is
+    # available, or a naïve version otherwise.
+    def self.demodulize(name)
+      name = name.to_s
+      if name.respond_to?(:demodulize)
+        name.demodulize.freeze
+      else
+        name.split(/::/)[-1].freeze
+      end
+    end
+
+    # Demodulizes and underscores the provided name.
+    def self.namify(name)
+      underscore(demodulize(name.to_s))
+    end
+
+    # Convert this_name to ThisName. Uses #camelize if +name+ responds to it,
+    # or a naïve version otherwise.
+    def self.camelize(name)
+      name = name.to_s
+      if name.respond_to?(:camelize)
+        name.camelize.freeze
+      else
+        "_#{name}".gsub(/_([a-z])/i) { $1.upcase }.freeze
+      end
+    end
+
+    # Define a new error as a subclass of the exception hosting ErrorDSL.
+    # Options is a Hash supporting the following values:
+    #
+    # +status+:: A number or Ruby symbol representing the HTTP status code
+    #            associated with this error. If not provided, defaults to
+    #            :bad_request. Must be provided if +class+ is provided. HTTP
+    #            status codes are defined in Rack::Utils.
+    # +key+::    The name of the error class to be created. Provide as a
+    #            snake_case value that will be turned into a camelized class
+    #            name. Mutually exclusive with +class+.
+    # +class+::  The name of the class the error is for. If present, +status+
+    #            must be provided to create a complete error class. That is,
+    #
+    #              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.
+    def define_error(options)
+      fail ArgumentError, 'invalid options' unless options.kind_of?(Hash)
+      fail ArgumentError, 'define what error?' if options.empty?
+
+      options = options.dup
+
+      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)}"
+              else
+                "#{klass}_#{KineticCafe::ErrorDSL.namify(self.name)}"
+              end
+      else
+        status = options[:status]
+        key    = options.fetch(:key) {
+          fail ArgumentError, 'one of :key or :class must be provided'
+        }.to_s
+      end
+
+      key.tap do |k|
+        k.squeeze!('_')
+        k.gsub!(/^_+/, '')
+        k.gsub!(/_+$/, '')
+        k.freeze
+      end
+
+      error_name = KineticCafe::ErrorDSL.camelize(key)
+      i18n_key_base = respond_to?(:i18n_key_base) && self.i18n_key_base ||
+        'kcerrors'.freeze
+      i18n_key = "#{i18n_key_base}.#{key}".freeze
+
+      if const_defined?(error_name)
+        message = "key:#{key} already exists as #{error_name}"
+        message << " with class:#{klass}" if klass
+        fail ArgumentError, message
+      end
+
+      error = Class.new(self)
+      error.send :define_method, :name, -> { key }
+      error.send :define_method, :i18n_key, -> { i18n_key }
+
+      if options[:header_only]
+        error.send :define_method, :header_only?, -> { true }
+      end
+
+      if options[:internal]
+        error.send :define_method, :internal?, -> { true }
+      end
+
+      status ||= defined?(Rack::Utils) && :bad_request || 400
+      status.freeze
+
+      error.send :define_method, :default_status, -> { status } if status
+      error.send :private, :default_status
+
+      const_set(error_name, error)
+    end
+
+    ##
+    # 
+
+
+    private
+
+    ##
+    def self.included(_mod)
+      fail "#{self} cannot be included"
+    end
+
+    ##
+    def self.extended(base)
+      unless base < ::StandardError
+        fail "#{self} cannot extend #{base} (not a StandardError)"
+      end
+
+      if defined?(Rack::Utils)
+        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))
+          end
+
+          base.send :define_error, status: name, key: name
+        end
+      end
+    end
+  end
+end