Module: KineticCafe::ErrorModule

Included in:
Error
Defined in:
lib/kinetic_cafe/error_module.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#extra ⇒ Object (readonly)

Extra data relevant to recipients of the exception, provided on construction.



11
12
13
 
# File 'lib/kinetic_cafe/error_module.rb', line 11

def extra
  @extra
end

#status ⇒ Object (readonly)

The HTTP status to be returned. If not provided in the constructor, uses #default_status.



8
9
10
 
# File 'lib/kinetic_cafe/error_module.rb', line 8

def status
  @status
end

Class Method Details

.included(mod) ⇒ Object 



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/kinetic_cafe/error_module.rb', line 214

def included(mod)
  default_singleton_method mod, :i18n_key_base do
    'kcerrors'.freeze
  end

  default_singleton_method mod, :i18n_params do
    [].freeze
  end

  default_singleton_method mod, :i18n_key do
    @i18n_key ||= [
      i18n_key_base, KineticCafe::ErrorDSL.namify(name)
    ].join('.').freeze
  end
end

Instance Method Details

#api_error ⇒ Object Also known as: as_json

The details of this error as a hash. Values that are empty or nil are omitted.



145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/kinetic_cafe/error_module.rb', line 145

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

#cause ⇒ Object

:attr_reader: The exception that caused this exception. Provided on exception construction or automatically through Ruby’s standard exception mechanism.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/kinetic_cafe/error_module.rb', line 17

def cause
  unless @initialized_cause
    begin
      initialize_cause(super) if !@initialized_cause && super
    rescue NoMethodError
      # We are suppressing this error because Exception#cause was
      # implemented in Ruby 2.1.
      @initialized_cause = true
      @cause = nil
    end
  end

  @cause
end

#error_result ⇒ Object

An error result that can be passed as a response body.



161
162
163
 
# File 'lib/kinetic_cafe/error_module.rb', line 161

def error_result
  { error: api_error, message: message }
end

#header? ⇒ Boolean Also known as: header_only?

Indicates that this error should not have its details rendered to the user, but should use the head method.

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/kinetic_cafe/error_module.rb', line 108

def header?
  false
end

#i18n_key ⇒ Object Also known as: code

The key used for I18n translation.



95
96
97
98
99
100
101
102
103
 
# File 'lib/kinetic_cafe/error_module.rb', line 95

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

#i18n_message(locale = nil) ⇒ Object

The I18n translation of the message. If I18n.translate is not defined, returns #i18n_key and the I18n parameters as an array.

If I18n is provided, the translation will be performed using the default locale. The message will be cached unless locale is provided, which selects a specific locale for translation.

locale may be provided as a bare locale (:en) or as a hash value (locale: :en).



128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/kinetic_cafe/error_module.rb', line 128

def i18n_message(locale = nil)
  if defined?(I18n.translate)
    case locale
    when Hash
      I18n.translate(i18n_key, @i18n_params.merge(locale))
    when nil
      @i18n_message ||= I18n.translate(i18n_key, @i18n_params).freeze
    else
      I18n.translate(i18n_key, @i18n_params.merge(locale: locale))
    end
  else
    @i18n_message ||= [ i18n_key, @i18n_params ].freeze
  end
end

#initialize(*args) ⇒ Object

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. This is only necessary for Ruby before 2.1 or when directly initializing the 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)



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/kinetic_cafe/error_module.rb', line 63

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)

  @initialized_cause = false
  initialize_cause(options.delete(:cause)) if options.key?(:cause)

  query = options.delete(:query)
  @i18n_params.merge!(query: stringify(query)) if query
  @i18n_params.merge!(options)
end

#inspect ⇒ Object

Nice debugging version of a KineticCafe::Error



174
175
176
177
178
179
 
# File 'lib/kinetic_cafe/error_module.rb', line 174

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

#internal? ⇒ Boolean

Indicates that this error should be rendered to the client, but clients are advised not to display the message to the user.

Returns:

  • (Boolean) 


115
116
117
 
# File 'lib/kinetic_cafe/error_module.rb', line 115

def internal?
  false
end

#json_result ⇒ Object Also known as: render_json_for_rails

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).



168
169
170
 
# File 'lib/kinetic_cafe/error_module.rb', line 168

def json_result
  { status: status, json: error_result, layout: false }
end

#message(locale = nil) ⇒ Object

The message associated with this exception. If not provided, defaults to #i18n_message, which is passed the optional locale.



85
86
87
 
# File 'lib/kinetic_cafe/error_module.rb', line 85

def message(locale = nil)
  @message || i18n_message(locale)
end

#name ⇒ Object

The name of the error class.



90
91
92
 
# File 'lib/kinetic_cafe/error_module.rb', line 90

def name
  @name ||= KineticCafe::ErrorDSL.namify(self.class.name)
end