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


296
297
298
 
# File 'lib/cmdx/result.rb', line 296

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) 


219
220
221
 
# File 'lib/cmdx/result.rb', line 219

def backtrace
  @signal.backtrace
end

#cause ⇒ Exception?

Returns:

  • (Exception, nil) 


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

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:



188
189
190
191
192
 
# File 'lib/cmdx/result.rb', line 188

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



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

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



61
62
63
 
# File 'lib/cmdx/result.rb', line 61

def cid
  chain.id
end

#complete? ⇒ Boolean

Returns:

  • (Boolean) 


92
93
94
 
# File 'lib/cmdx/result.rb', line 92

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



76
77
78
 
# File 'lib/cmdx/result.rb', line 76

def context
  @task.context
end

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

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

Returns:

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


343
344
345
 
# File 'lib/cmdx/result.rb', line 343

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


336
337
338
 
# File 'lib/cmdx/result.rb', line 336

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



239
240
241
 
# File 'lib/cmdx/result.rb', line 239

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

#duration ⇒ Float?

Returns lifecycle duration in milliseconds.

Returns:

  • (Float, nil) —

    lifecycle duration in milliseconds



249
250
251
 
# File 'lib/cmdx/result.rb', line 249

def duration
  @options[:duration]
end

#errors ⇒ Errors

Returns frozen by Runtime teardown.

Returns:

  • (Errors) —

    frozen by Runtime teardown



82
83
84
 
# File 'lib/cmdx/result.rb', line 82

def errors
  @task.errors
end

#failed? ⇒ Boolean

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/cmdx/result.rb', line 117

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



66
67
68
 
# File 'lib/cmdx/result.rb', line 66

def index
  @chain.index(self)
end

#interrupted? ⇒ Boolean

Returns:

  • (Boolean) 


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

def interrupted?
  @signal.interrupted?
end

#ko? ⇒ Boolean

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/cmdx/result.rb', line 127

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



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

def metadata
  @signal.metadata
end

#ok? ⇒ Boolean

Returns:

  • (Boolean) 


122
123
124
 
# File 'lib/cmdx/result.rb', line 122

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



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

def on(*keys)
  raise ArgumentError, "block required" unless block_given?

  yield(self) if keys.any? do |k|
    unless EVENTS.include?(k.to_sym)
      raise ArgumentError,
        "unknown event #{k.inspect}, must be one of #{EVENTS.join(', ')}"
    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:



174
175
176
 
# File 'lib/cmdx/result.rb', line 174

def origin
  @signal.origin
end

#reason ⇒ String?

Returns:

  • (String, nil) 


160
161
162
 
# File 'lib/cmdx/result.rb', line 160

def reason
  @signal.reason
end

#retried? ⇒ Boolean

Returns:

  • (Boolean) 


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

def retried?
  retries.positive?
end

#retries ⇒ Integer

Returns:

  • (Integer) 


224
225
226
 
# File 'lib/cmdx/result.rb', line 224

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



244
245
246
 
# File 'lib/cmdx/result.rb', line 244

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



71
72
73
 
# File 'lib/cmdx/result.rb', line 71

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

#skipped? ⇒ Boolean

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/cmdx/result.rb', line 112

def skipped?
  @signal.skipped?
end

#state ⇒ String

Returns one of Signal::STATES.

Returns:



87
88
89
 
# File 'lib/cmdx/result.rb', line 87

def state
  @signal.state
end

#status ⇒ String

Returns one of Signal::STATUSES.

Returns:



102
103
104
 
# File 'lib/cmdx/result.rb', line 102

def status
  @signal.status
end

#strict? ⇒ Boolean

Returns true when produced via ‘execute!`.

Returns:

  • (Boolean) —

    true when produced via ‘execute!`



234
235
236
 
# File 'lib/cmdx/result.rb', line 234

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

#success? ⇒ Boolean

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/cmdx/result.rb', line 107

def success?
  @signal.success?
end

#tags ⇒ Array<Symbol, String>

Returns:

  • (Array<Symbol, String>) 


254
255
256
 
# File 'lib/cmdx/result.rb', line 254

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:



203
204
205
206
207
 
# File 'lib/cmdx/result.rb', line 203

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



210
211
212
 
# File 'lib/cmdx/result.rb', line 210

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.



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/cmdx/result.rb', line 261

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) 


306
307
308
 
# File 'lib/cmdx/result.rb', line 306

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



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/cmdx/result.rb', line 312

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 correlation id or the global configuration’s correlation id.

Returns:

  • (String, nil) —

    correlation id or the global configuration’s correlation id



56
57
58
 
# File 'lib/cmdx/result.rb', line 56

def xid
  chain.xid
end