Class: CDC::Core::ProcessorResult

Inherits:
Object
  • Object
show all
Defined in:
lib/cdc/core/processor_result.rb

Overview

Result returned by processors and pipelines.

ProcessorResult standardizes processor outcomes so callers can distinguish successful processing, skipped events, and failures without relying on processor-specific return values.

Constant Summary collapse

VALID_STATUSES =

Allowed result statuses.

Ractor.make_shareable(%i[success failure skipped].freeze)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(status, event: nil, error: nil, metadata: {}, value: event) ⇒ ProcessorResult

Build a processor result with an explicit status.

Parameters:

  • status (#to_sym) —

    result status

  • event (ChangeEvent, nil) (defaults to: nil) —

    associated event

  • error (Exception, nil) (defaults to: nil) —

    associated failure

  • metadata (Hash, EventMetadata) (defaults to: {}) —

    result metadata

  • value (Object, nil) (defaults to: event) —

    value produced by the processor



66
67
68
69
70
71
72
73
 
# File 'lib/cdc/core/processor_result.rb', line 66

def initialize(status, event: nil, error: nil, metadata: {}, value: event)
  @status = normalize_status(status)
  @event = event
  @value = value
  @error = error
  @metadata = metadata.is_a?(EventMetadata) ? metadata : EventMetadata.new(metadata)
  make_shareable_when_possible
end

Instance Attribute Details

#error ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, Object, nil) —

    event or input associated with the result

  • (Object, nil) —

    value produced by the processor

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



19
20
21
 
# File 'lib/cdc/core/processor_result.rb', line 19

def error
  @error
end

#event ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, Object, nil) —

    event or input associated with the result

  • (Object, nil) —

    value produced by the processor

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



19
20
21
 
# File 'lib/cdc/core/processor_result.rb', line 19

def event
  @event
end

#metadata ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, Object, nil) —

    event or input associated with the result

  • (Object, nil) —

    value produced by the processor

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



19
20
21
 
# File 'lib/cdc/core/processor_result.rb', line 19

def metadata
  @metadata
end

#status ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, Object, nil) —

    event or input associated with the result

  • (Object, nil) —

    value produced by the processor

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



19
20
21
 
# File 'lib/cdc/core/processor_result.rb', line 19

def status
  @status
end

#value ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, Object, nil) —

    event or input associated with the result

  • (Object, nil) —

    value produced by the processor

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



19
20
21
 
# File 'lib/cdc/core/processor_result.rb', line 19

def value
  @value
end

Class Method Details

.failure(error, event: nil, reason: nil, retryable: nil, processor: nil, failed_at: nil, metadata: nil) ⇒ ProcessorResult

Build a failure result.

Parameters:

  • error (Exception) —

    processor error

  • event (ChangeEvent, nil) (defaults to: nil) —

    event being processed

  • reason (String, nil) (defaults to: nil) —

    human-readable failure reason

  • retryable (Boolean, nil) (defaults to: nil) —

    whether the failure can be retried

  • processor (String, nil) (defaults to: nil) —

    processor name associated with the failure

  • failed_at (String, nil) (defaults to: nil) —

    timestamp for when the failure occurred

  • metadata (Hash, EventMetadata) (defaults to: nil) —

    result metadata

Returns:



39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/cdc/core/processor_result.rb', line 39

def self.failure(error, event: nil, reason: nil, retryable: nil, processor: nil, failed_at: nil,
                 metadata: nil)
  base_metadata = metadata.nil? ? EventMetadata.new.to_h : metadata.to_h
  failure_metadata = base_metadata.merge(
    reason: reason || error.message,
    retryable: retryable,
    processor: processor || error.class.name,
    failed_at: failed_at || Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%6NZ')
  ).compact

  new(:failure, event:, error:, metadata: failure_metadata)
end

.skipped(event = nil, metadata: {}) ⇒ ProcessorResult

Build a skipped result.

Parameters:

  • event (ChangeEvent, nil) (defaults to: nil) —

    skipped event

  • metadata (Hash, EventMetadata) (defaults to: {}) —

    result metadata

Returns:



57
 
# File 'lib/cdc/core/processor_result.rb', line 57

def self.skipped(event = nil, metadata: {}) = new(:skipped, event:, metadata:)

.success(event = nil, metadata: {}, value: event) ⇒ ProcessorResult

Build a successful result.

Parameters:

  • event (ChangeEvent, nil) (defaults to: nil) —

    processed event

  • metadata (Hash, EventMetadata) (defaults to: {}) —

    result metadata

  • value (Object, nil) (defaults to: event) —

    value produced by the processor; defaults to event for compatibility

Returns:



27
 
# File 'lib/cdc/core/processor_result.rb', line 27

def self.success(event = nil, metadata: {}, value: event) = new(:success, event:, metadata:, value:)

Instance Method Details

#error_backtrace ⇒ Array<String>

Error backtrace, when present.

Returns:

  • (Array<String>) 


129
130
131
 
# File 'lib/cdc/core/processor_result.rb', line 129

def error_backtrace
  Array(error&.backtrace)
end

#error_class ⇒ String?

Error class name, when present.

Returns:

  • (String, nil) 


115
116
117
 
# File 'lib/cdc/core/processor_result.rb', line 115

def error_class
  error&.class&.name
end

#error_message ⇒ String?

Error message, when present.

Returns:

  • (String, nil) 


122
123
124
 
# File 'lib/cdc/core/processor_result.rb', line 122

def error_message
  error&.message
end

#failed_at ⇒ String?

Timestamp for when the failure occurred, when present.

Returns:

  • (String, nil) 


108
109
110
 
# File 'lib/cdc/core/processor_result.rb', line 108

def failed_at
  metadata[:failed_at]
end

#failure? ⇒ Boolean

Returns true when status is :failure.

Returns:

  • (Boolean) —

    true when status is :failure



79
 
# File 'lib/cdc/core/processor_result.rb', line 79

def failure? = status == :failure

#failure_reason ⇒ String?

Human-readable failure reason, when present.

Returns:

  • (String, nil) 


87
88
89
 
# File 'lib/cdc/core/processor_result.rb', line 87

def failure_reason
  metadata[:reason]
end

#processor_name ⇒ String?

Name of the processor associated with the failure, when present.

Returns:

  • (String, nil) 


101
102
103
 
# File 'lib/cdc/core/processor_result.rb', line 101

def processor_name
  metadata[:processor]
end

#retryable? ⇒ Boolean

Whether the failure is retryable.

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/cdc/core/processor_result.rb', line 94

def retryable?
  metadata[:retryable] == true
end

#skipped? ⇒ Boolean

Returns true when status is :skipped.

Returns:

  • (Boolean) —

    true when status is :skipped



82
 
# File 'lib/cdc/core/processor_result.rb', line 82

def skipped? = status == :skipped

#success? ⇒ Boolean

Returns true when status is :success.

Returns:

  • (Boolean) —

    true when status is :success



76
 
# File 'lib/cdc/core/processor_result.rb', line 76

def success? = status == :success

#to_h ⇒ Hash{String=>Object,nil}

Convert the result into a shareable hash.

Returns:

  • (Hash{String=>Object,nil}) 


136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/cdc/core/processor_result.rb', line 136

def to_h
  payload = {
    'status' => status,
    'event' => event.respond_to?(:to_h) ? event.to_h : event,
    'value' => value.respond_to?(:to_h) ? value.to_h : value,
    'error_class' => error_class,
    'error_message' => error_message,
    'error_backtrace' => error_backtrace,
    'metadata' => metadata.to_h
  }

  Ractor.make_shareable(payload.freeze)
end