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