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



100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/cmdx/fault.rb', line 100

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.



97
98
99
 
# File 'lib/cmdx/fault.rb', line 97

def result
  @result
end

Class Method Details

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

Note:

Each call allocates a new anonymous subclass. Hoist the matcher to module scope (‘MY_FAULT = CMDx::Fault.for?(MyTask)`) when used on hot paths to avoid class allocation churn over time.

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



33
34
35
36
37
38
39
40
 
# File 'lib/cmdx/fault.rb', line 33

def for?(*tasks)
  tasks = tasks.flatten
  raise ArgumentError, "Fault.for? requires at least one Task class" if tasks.empty?

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

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

Note:

Each call allocates a new anonymous subclass. Hoist the matcher to module scope when used on hot paths to avoid class allocation churn.

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



78
79
80
81
82
 
# File 'lib/cmdx/fault.rb', line 78

def matches?(&block)
  raise ArgumentError, "Fault.matches? requires a block" unless block

  matcher(&block)
end

.reason?(reason) ⇒ Class<Fault>

Note:

Each call allocates a new anonymous subclass. Hoist the matcher to module scope (‘PAYMENT_FAULT = CMDx::Fault.reason?(“Payment failed”)`) when used on hot paths to avoid class allocation churn.

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



59
60
61
62
63
64
65
 
# File 'lib/cmdx/fault.rb', line 59

def reason?(reason)
  raise ArgumentError, "Fault.reason? requires a reason" 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



123
124
125
 
# File 'lib/cmdx/fault.rb', line 123

def chain
  @result.chain
end

#context ⇒ Context

Returns the failed task’s context.

Returns:

  • (Context) —

    the failed task’s context



118
119
120
 
# File 'lib/cmdx/fault.rb', line 118

def context
  @result.context
end

#task ⇒ Class<Task>

Returns the failing task class.

Returns:

  • (Class<Task>) —

    the failing task class



113
114
115
 
# File 'lib/cmdx/fault.rb', line 113

def task
  @result.task
end