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)
EMPTY_METADATA = 
Ractor.make_shareable(
  {} # : Hash[untyped, untyped]
    .freeze
)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(status, event: nil, error: nil, metadata: EMPTY_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: EMPTY_METADATA) —

    result metadata

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

    value produced by the processor



70
71
72
73
74
75
76
77
 
# File 'lib/cdc/core/processor_result.rb', line 70

def initialize(status, event: nil, error: nil, metadata: EMPTY_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



23
24
25
 
# File 'lib/cdc/core/processor_result.rb', line 23

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



23
24
25
 
# File 'lib/cdc/core/processor_result.rb', line 23

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



23
24
25
 
# File 'lib/cdc/core/processor_result.rb', line 23

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



23
24
25
 
# File 'lib/cdc/core/processor_result.rb', line 23

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



23
24
25
 
# File 'lib/cdc/core/processor_result.rb', line 23

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:



43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/cdc/core/processor_result.rb', line 43

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: EMPTY_METADATA) ⇒ ProcessorResult

Build a skipped result.

Parameters:

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

    skipped event

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

    result metadata

Returns:



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

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

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

Build a successful result.

Parameters:

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

    processed event

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

    result metadata

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

    value produced by the processor; defaults to event for compatibility

Returns:



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

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

Instance Method Details

#error_backtrace ⇒ Array<String>

Error backtrace, when present.

Returns:

  • (Array<String>) —

    backtrace from the associated error



133
134
135
 
# File 'lib/cdc/core/processor_result.rb', line 133

def error_backtrace
  Array(error&.backtrace)
end

#error_class ⇒ String?

Error class name, when present.

Returns:

  • (String, nil) —

    class name of the associated error



119
120
121
 
# File 'lib/cdc/core/processor_result.rb', line 119

def error_class
  error&.class&.name
end

#error_message ⇒ String?

Error message, when present.

Returns:

  • (String, nil) —

    message from the associated error



126
127
128
 
# File 'lib/cdc/core/processor_result.rb', line 126

def error_message
  error&.message
end

#failed_at ⇒ String?

Timestamp for when the failure occurred, when present.

Returns:

  • (String, nil) —

    timestamp for when the failure occurred



112
113
114
 
# File 'lib/cdc/core/processor_result.rb', line 112

def failed_at
  metadata[:failed_at]
end

#failure? ⇒ Boolean

Returns true when status is :failure.

Returns:

  • (Boolean) —

    true when status is :failure



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

def failure? = status == :failure

#failure_reason ⇒ String?

Human-readable failure reason, when present.

Returns:

  • (String, nil) —

    human-readable failure reason



91
92
93
 
# File 'lib/cdc/core/processor_result.rb', line 91

def failure_reason
  metadata[:reason]
end

#processor_name ⇒ String?

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

Returns:

  • (String, nil) —

    processor name associated with the failure



105
106
107
 
# File 'lib/cdc/core/processor_result.rb', line 105

def processor_name
  metadata[:processor]
end

#retryable? ⇒ Boolean

Whether the failure is retryable.

Returns:

  • (Boolean) —

    true when metadata marks the failure retryable



98
99
100
 
# File 'lib/cdc/core/processor_result.rb', line 98

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

#skipped? ⇒ Boolean

Returns true when status is :skipped.

Returns:

  • (Boolean) —

    true when status is :skipped



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

def skipped? = status == :skipped

#success? ⇒ Boolean

Returns true when status is :success.

Returns:

  • (Boolean) —

    true when status is :success



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

def success? = status == :success

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

Convert the result into a shareable hash.

Returns:

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

    Ractor-shareable result representation



140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/cdc/core/processor_result.rb', line 140

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