Class: CMDx::Fault

Inherits:
Error
  • Object
show all
Defined in:
lib/cmdx/fault.rb

Overview

Exception raised by ‘execute!` (strict mode) when a task fails. Carries the originating Result (deepest in any propagation chain) and exposes `task`, `signal`, `context`, and `chain` as delegators. The backtrace is cleaned through the configured `backtrace_cleaner` when present.

Use Fault.for? or Fault.matches? to build matcher subclasses suitable for ‘rescue` clauses.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(result) ⇒ Fault

Returns a new instance of Fault.

Parameters:

  • result (Result) —

    the failed result this Fault represents



88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/cmdx/fault.rb', line 88

def initialize(result)
  @result = result

  super(I18nProxy.tr(result.reason))

  if (frames = result.backtrace || result.cause&.backtrace_locations)
    frames = frames.map(&:to_s)
    frames = task.settings.backtrace_cleaner&.call(frames) || frames
    set_backtrace(frames)
  end
end

Instance Attribute Details

#result ⇒ Object (readonly)

Returns the value of attribute result.



85
86
87
 
# File 'lib/cmdx/fault.rb', line 85

def result
  @result
end

Class Method Details

.for?(*tasks) ⇒ Class<Fault>

Returns a matcher subclass that matches Faults whose ‘task` is (or inherits from) any of the given task classes. Suitable for use in `rescue`.

Examples:

begin
  MyTask.execute!(ctx)
rescue Fault.for?(ProcessOrder, ChargeCard) => fault
  Alert.for_fault(fault)
end

Parameters:

  • tasks (Array<Class>) —

    one or more Task classes

Returns:

  • (Class<Fault>) —

    anonymous matcher subclass

Raises:

  • (ArgumentError) —

    when no tasks are given



29
30
31
32
33
34
35
36
 
# File 'lib/cmdx/fault.rb', line 29

def for?(*tasks)
  tasks = tasks.flatten
  raise ArgumentError, "at least one task required" if tasks.empty?

  matcher do |other|
    tasks.any? { |task| other.task <= task }
  end
end

.matches?(&block) {|fault| ... } ⇒ Class<Fault>

Returns a matcher subclass whose ‘===` runs `block` against the fault.

Parameters:

  • block (#call) —

    ‘(fault) -> Boolean` matcher body

Yield Parameters:

Yield Returns:

  • (Boolean)

Returns:

  • (Class<Fault>) —

    anonymous matcher subclass

Raises:

  • (ArgumentError) —

    when no block is given



66
67
68
69
70
 
# File 'lib/cmdx/fault.rb', line 66

def matches?(&block)
  raise ArgumentError, "block required" unless block

  matcher(&block)
end

.reason?(reason) ⇒ Class<Fault>

Returns a matcher subclass that matches Faults whose ‘result.reason` is equal to the given string. Suitable for use in `rescue`.

Examples:

begin
  MyTask.execute!(ctx)
rescue Fault.reason?("Payment failed") => fault
  Alert.for_fault(fault)
end

Parameters:

  • reason (String) —

    the reason to match

Returns:

  • (Class<Fault>) —

    anonymous matcher subclass

Raises:

  • (ArgumentError) —

    when no reason is given



51
52
53
54
55
56
57
 
# File 'lib/cmdx/fault.rb', line 51

def reason?(reason)
  raise ArgumentError, "reason required" unless reason

  matcher do |other|
    other.result.reason == reason
  end
end

Instance Method Details

#chain ⇒ Chain

Returns the chain the failed result belongs to.

Returns:

  • (Chain) —

    the chain the failed result belongs to



111
112
113
 
# File 'lib/cmdx/fault.rb', line 111

def chain
  @result.chain
end

#context ⇒ Context

Returns the failed task’s context.

Returns:

  • (Context) —

    the failed task’s context



106
107
108
 
# File 'lib/cmdx/fault.rb', line 106

def context
  @result.context
end

#task ⇒ Class<Task>

Returns the failing task class.

Returns:

  • (Class<Task>) —

    the failing task class



101
102
103
 
# File 'lib/cmdx/fault.rb', line 101

def task
  @result.task
end