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.



15
16
17
 
# File 'lib/kinetic_cafe/error_module.rb', line 15

def extra
  @extra
end

#severity ⇒ Object (readonly)

The severity to be returned. If not provided in the constructor, uses #default_severity



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

def severity
  @severity
end

#status ⇒ Object (readonly)

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



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

def status
  @status
end

Class Method Details

.included(mod) ⇒ Object 



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/kinetic_cafe/error_module.rb', line 266

def included(mod)
  default_singleton_method mod, :i18n_key_base do
    'kcerrors'
  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.



151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/kinetic_cafe/error_module.rb', line 151

def api_error(*)
  {
    message:      @message,
    status:       status,
    severity:     severity,
    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.



21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/kinetic_cafe/error_module.rb', line 21

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.



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

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) 


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

def header?
  false
end

#i18n_key ⇒ Object Also known as: code

The key used for I18n translation.



103
104
105
106
107
108
109
 
# File 'lib/kinetic_cafe/error_module.rb', line 103

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



134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/kinetic_cafe/error_module.rb', line 134

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.

severity

An override to the default severity to be returned by this error.

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)



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/kinetic_cafe/error_module.rb', line 69

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
  @severity    = options.delete(:severity) || default_severity
  @i18n_params = options.delete(:i18n_params) || {}
  @extra       = options.delete(:extra)

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

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

#inspect ⇒ Object

Nice debugging version of a KineticCafe::Error



181
182
183
184
185
186
 
# File 'lib/kinetic_cafe/error_module.rb', line 181

def inspect
  "#<#{self.class}: name=#{name} status=#{status} " \
    "severity=#{severity} 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) 


121
122
123
 
# File 'lib/kinetic_cafe/error_module.rb', line 121

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



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

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.



93
94
95
 
# File 'lib/kinetic_cafe/error_module.rb', line 93

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

#name ⇒ Object

The name of the error class.



98
99
100
 
# File 'lib/kinetic_cafe/error_module.rb', line 98

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