Class: CMDx::Result

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

Overview

Frozen outcome of a task execution. Provides read-only access to the task’s signal (state/status/reason/metadata/cause), the chain it belongs to, its context, and lifecycle metadata (retries, duration, rollback, deprecated). Constructed by Runtime at the end of ‘execute`.

See Also:

  • CMDx::Runtime#finalize_result
  • Signal

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(chain, task, signal, **options) ⇒ Result

Returns a new instance of Result.

Parameters:

  • chain (Chain) —

    the chain this result belongs to

  • task (Task) —

    the executed task instance

  • signal (Signal) —

    the final signal from the task’s lifecycle

  • options (Hash{Symbol => Object}) —

    frozen execution metadata

Options Hash (**options):

  • :tid (String)
  • :strict (Boolean)
  • :deprecated (Boolean)
  • :rolled_back (Boolean)
  • :retries (Integer)
  • :duration (Float) —

    milliseconds



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

def initialize(chain, task, signal, **options)
  @chain   = chain
  @task    = task
  @signal  = signal
  @options = options.freeze
end

Instance Attribute Details

#chain ⇒ Object (readonly)

Returns the value of attribute chain.



21
22
23
 
# File 'lib/cmdx/result.rb', line 21

def chain
  @chain
end

Instance Method Details

#as_json ⇒ Hash{Symbol => Object}

JSON-friendly hash view. Aliases the memoized #to_h for conventional ‘as_json` callers (e.g. Rails).

Returns:

  • (Hash{Symbol => Object}) 


314
315
316
 
# File 'lib/cmdx/result.rb', line 314

def as_json(*)
  to_h
end

#backtrace ⇒ Array<String>?

The backtrace captured by ‘fail!` / `throw!` for Fault propagation. `nil` when this result is not a failure or the failure didn’t capture a backtrace.

Returns:

  • (Array<String>, nil) 


237
238
239
 
# File 'lib/cmdx/result.rb', line 237

def backtrace
  @signal.backtrace
end

#cause ⇒ Exception?

Returns:

  • (Exception, nil) 


183
184
185
 
# File 'lib/cmdx/result.rb', line 183

def cause
  @signal.cause
end

#caused_failure ⇒ Result?

The originating failed result at the bottom of the propagation chain. Walks ‘origin` recursively. `self` when this result is the originator; `nil` when not failed.

Returns:



206
207
208
209
210
 
# File 'lib/cmdx/result.rb', line 206

def caused_failure
  return unless failed?

  @caused_failure ||= origin ? origin.caused_failure : self
end

#caused_failure? ⇒ Boolean

Returns true when this result originated the failure chain.

Returns:

  • (Boolean) —

    true when this result originated the failure chain



213
214
215
 
# File 'lib/cmdx/result.rb', line 213

def caused_failure?
  failed? && origin.nil?
end

#cid ⇒ String

Returns uuid_v7 identifier for the chain this result belongs to.

Returns:

  • (String) —

    uuid_v7 identifier for the chain this result belongs to



63
64
65
 
# File 'lib/cmdx/result.rb', line 63

def cid
  chain.id
end

#complete? ⇒ Boolean

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/cmdx/result.rb', line 94

def complete?
  @signal.complete?
end

#context ⇒ Context Also known as: ctx

Returns frozen after the root task’s teardown.

Returns:

  • (Context) —

    frozen after the root task’s teardown



78
79
80
 
# File 'lib/cmdx/result.rb', line 78

def context
  @task.context
end

#deconstruct ⇒ Array<Array(Symbol, Object)>

Pattern-matching support for ‘case result in […]`.

Returns:

  • (Array<Array(Symbol, Object)>) 


361
362
363
 
# File 'lib/cmdx/result.rb', line 361

def deconstruct
  to_h.to_a
end

#deconstruct_keys(keys) ⇒ Hash{Symbol => Object}

Pattern-matching support for ‘case result in …`.

Parameters:

  • keys (Array<Symbol>, nil) —

    restrict the returned hash to these keys

Returns:

  • (Hash{Symbol => Object}) 


354
355
356
 
# File 'lib/cmdx/result.rb', line 354

def deconstruct_keys(keys)
  keys.nil? ? to_h : to_h.slice(*keys)
end

#deprecated? ⇒ Boolean

Returns true when the task class is marked deprecated.

Returns:

  • (Boolean) —

    true when the task class is marked deprecated



257
258
259
 
# File 'lib/cmdx/result.rb', line 257

def deprecated?
  !!@options[:deprecated]
end

#duration ⇒ Float?

Returns lifecycle duration in milliseconds.

Returns:

  • (Float, nil) —

    lifecycle duration in milliseconds



267
268
269
 
# File 'lib/cmdx/result.rb', line 267

def duration
  @options[:duration]
end

#error ⇒ Exception, ...

Convenience accessor that returns the underlying exception when the failure was produced by a rescued exception, otherwise the human ‘reason`. `nil` for non-failed results. Useful for telemetry adapters (Sentry, Bugsnag, …) that branch on whether an exception is available without forcing every subscriber to repeat the `cause || reason` dance.

Returns:

  • (Exception, String, nil) 


195
196
197
198
199
 
# File 'lib/cmdx/result.rb', line 195

def error
  return unless failed?

  cause || reason
end

#errors ⇒ Errors

Returns frozen by Runtime teardown.

Returns:

  • (Errors) —

    frozen by Runtime teardown



84
85
86
 
# File 'lib/cmdx/result.rb', line 84

def errors
  @task.errors
end

#failed? ⇒ Boolean

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/cmdx/result.rb', line 119

def failed?
  @signal.failed?
end

#index ⇒ Integer?

Returns this result’s position in the chain.

Returns:

  • (Integer, nil) —

    this result’s position in the chain



68
69
70
 
# File 'lib/cmdx/result.rb', line 68

def index
  @chain.index(self)
end

#interrupted? ⇒ Boolean

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/cmdx/result.rb', line 99

def interrupted?
  @signal.interrupted?
end

#ko? ⇒ Boolean

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/cmdx/result.rb', line 129

def ko?
  @signal.ko?
end

#metadata ⇒ Hash{Symbol => Object}

Returns frozen empty hash when none provided.

Returns:

  • (Hash{Symbol => Object}) —

    frozen empty hash when none provided



169
170
171
 
# File 'lib/cmdx/result.rb', line 169

def metadata
  @signal.metadata
end

#ok? ⇒ Boolean

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/cmdx/result.rb', line 124

def ok?
  @signal.ok?
end

#on(*keys) {|result| ... } ⇒ Result

Dispatches the block when any of ‘keys` matches a truthy predicate on this result. Returns `self` for chaining.

Examples:

result
  .on(:success) { |r| deliver(r.context) }
  .on(:failed)  { |r| alert(r.reason) }

Parameters:

  • keys (Array<Symbol, String>) —

    any of the predicate bases: ‘complete`, `interrupted`, `success`, `skipped`, `failed`, `ok`, `ko`

Yield Parameters:

  • result (Result) —

    this result

Returns:

  • (Result) —

    self for chaining

Raises:

  • (ArgumentError) —

    when no block is given or a key is unknown



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/cmdx/result.rb', line 146

def on(*keys)
  raise ArgumentError, "Result#on requires a block" unless block_given?

  yield(self) if keys.any? do |k|
    unless EVENTS.include?(k.to_sym)
      raise ArgumentError, <<~MSG.chomp
        unknown Result#on event #{k.inspect}, must be one of #{EVENTS.to_a.inspect}.
        See https://drexed.github.io/cmdx/outcomes/result/#predicate-dispatch
      MSG
    end

    public_send(:"#{k}?")
  end

  self
end

#origin ⇒ Result?

The upstream failed result this one was echoed from (via ‘Task#throw!` or a rescued Fault inside `work`). `nil` when this is a locally originated failure or the result didn’t fail.

Returns:



178
179
180
 
# File 'lib/cmdx/result.rb', line 178

def origin
  @signal.origin
end

#reason ⇒ String?

Returns:

  • (String, nil) 


164
165
166
 
# File 'lib/cmdx/result.rb', line 164

def reason
  @signal.reason
end

#retried? ⇒ Boolean

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/cmdx/result.rb', line 247

def retried?
  retries.positive?
end

#retries ⇒ Integer

Returns:

  • (Integer) 


242
243
244
 
# File 'lib/cmdx/result.rb', line 242

def retries
  @options[:retries] || 0
end

#rolled_back? ⇒ Boolean

Returns true when a failing task’s ‘rollback` ran.

Returns:

  • (Boolean) —

    true when a failing task’s ‘rollback` ran



262
263
264
 
# File 'lib/cmdx/result.rb', line 262

def rolled_back?
  !!@options[:rolled_back]
end

#root? ⇒ Boolean

Returns true when this result is the root of the chain.

Returns:

  • (Boolean) —

    true when this result is the root of the chain



73
74
75
 
# File 'lib/cmdx/result.rb', line 73

def root?
  !!@options[:root]
end

#skipped? ⇒ Boolean

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/cmdx/result.rb', line 114

def skipped?
  @signal.skipped?
end

#state ⇒ String

Returns one of Signal::STATES.

Returns:



89
90
91
 
# File 'lib/cmdx/result.rb', line 89

def state
  @signal.state
end

#status ⇒ String

Returns one of Signal::STATUSES.

Returns:



104
105
106
 
# File 'lib/cmdx/result.rb', line 104

def status
  @signal.status
end

#strict? ⇒ Boolean

Returns true when produced via ‘execute!`.

Returns:

  • (Boolean) —

    true when produced via ‘execute!`



252
253
254
 
# File 'lib/cmdx/result.rb', line 252

def strict?
  !!@options[:strict]
end

#success? ⇒ Boolean

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/cmdx/result.rb', line 109

def success?
  @signal.success?
end

#tags ⇒ Array<Symbol, String>

Returns:

  • (Array<Symbol, String>) 


272
273
274
 
# File 'lib/cmdx/result.rb', line 272

def tags
  task.settings.tags
end

#task ⇒ Class<Task>

Returns the task class that ran.

Returns:

  • (Class<Task>) —

    the task class that ran



46
47
48
 
# File 'lib/cmdx/result.rb', line 46

def task
  @task.class
end

#threw_failure ⇒ Result?

The nearest upstream failed result. ‘self` when this result is the originator; `nil` when not failed.

Returns:



221
222
223
224
225
 
# File 'lib/cmdx/result.rb', line 221

def threw_failure
  return unless failed?

  origin || self
end

#thrown_failure? ⇒ Boolean

Returns true when this result re-threw an upstream failure.

Returns:

  • (Boolean) —

    true when this result re-threw an upstream failure



228
229
230
 
# File 'lib/cmdx/result.rb', line 228

def thrown_failure?
  failed? && !origin.nil?
end

#tid ⇒ String

Returns uuid_v7 identifier for this execution.

Returns:

  • (String) —

    uuid_v7 identifier for this execution



41
42
43
 
# File 'lib/cmdx/result.rb', line 41

def tid
  @options[:tid]
end

#to_h ⇒ Hash{Symbol => Object}

Returns memoized serialization. Includes ‘:cause`, `:origin`, `:threw_failure`, `:caused_failure`, `:rolled_back` on failure.

Returns:

  • (Hash{Symbol => Object}) —

    memoized serialization. Includes ‘:cause`, `:origin`, `:threw_failure`, `:caused_failure`, `:rolled_back` on failure.



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/cmdx/result.rb', line 279

def to_h
  @to_h ||= {
    xid:,
    cid:,
    index:,
    root: root?,
    type:,
    task:,
    tid:,
    context:,
    state:,
    status:,
    reason:,
    metadata:,
    strict: strict?,
    deprecated: deprecated?,
    retried: retried?,
    retries:,
    duration:,
    tags:
  }.tap do |hash|
    if failed?
      hash[:cause] = cause
      hash[:origin] = hash_for_failure(:origin)
      hash[:threw_failure] = hash_for_failure(:threw_failure)
      hash[:caused_failure] = hash_for_failure(:caused_failure)
      hash[:rolled_back] = rolled_back?
    end
  end
end

#to_json(*args) ⇒ String

Serializes the result to a JSON string. Non-primitive entries (the ‘:task` Class, `:cause` Exception) emit via their stdlib `to_json` defaults; `:context` delegates to Context#to_json.

Parameters:

  • args (Array) —

    forwarded to ‘Hash#to_json`

Returns:

  • (String) 


324
325
326
 
# File 'lib/cmdx/result.rb', line 324

def to_json(*args)
  to_h.to_json(*args)
end

#to_s ⇒ String

Returns space-separated ‘key=value.inspect` pairs; failure references render as `<TaskClass uuid>`.

Returns:

  • (String) —

    space-separated ‘key=value.inspect` pairs; failure references render as `<TaskClass uuid>`.



330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/cmdx/result.rb', line 330

def to_s
  @to_s ||= begin
    buf = String.new(capacity: 256)

    to_h.each_with_object(buf) do |(k, v), buf|
      buf << " " unless buf.empty?

      ks = k.name

      if v.nil?
        buf << ks << "=nil"
      elsif ks == "origin" || ks.end_with?("_failure")
        buf << ks << "=<" << v[:task].to_s << " " << v[:tid] << ">"
      else
        buf << ks << "=" << v.inspect
      end
    end
  end
end

#type ⇒ String

Returns ‘“Task”` or `“Workflow”`.

Returns:

  • (String) —

    ‘“Task”` or `“Workflow”`



51
52
53
 
# File 'lib/cmdx/result.rb', line 51

def type
  task.type
end

#xid ⇒ String?

Returns resolved correlation id from this result’s chain (produced by the configured ‘correlation_id` callable when the root chain was acquired).

Returns:

  • (String, nil) —

    resolved correlation id from this result’s chain (produced by the configured ‘correlation_id` callable when the root chain was acquired)



58
59
60
 
# File 'lib/cmdx/result.rb', line 58

def xid
  chain.xid
end