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: {}) ⇒ 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



63
64
65
66
67
68
69
 
# File 'lib/cdc/core/processor_result.rb', line 63

def initialize(status, event: nil, error: nil, metadata: {})
  @status = normalize_status(status)
  @event = event
  @error = error
  @metadata = metadata.is_a?(EventMetadata) ? metadata : EventMetadata.new(metadata)
  Ractor.make_shareable(self) unless error
end

Instance Attribute Details

#error ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, nil) —

    event associated with the result

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



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

def error
  @error
end

#event ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, nil) —

    event associated with the result

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



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

def event
  @event
end

#metadata ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, nil) —

    event associated with the result

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



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

def metadata
  @metadata
end

#status ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    result status

  • (ChangeEvent, nil) —

    event associated with the result

  • (Exception, nil) —

    failure error, when status is :failure

  • (EventMetadata) —

    result metadata



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

def status
  @status
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:



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

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:



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

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

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

Build a successful result.

Parameters:

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

    processed event

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

    result metadata

Returns:



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

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

Instance Method Details

#error_backtrace ⇒ Array<String>

Error backtrace, when present.

Returns:

  • (Array<String>) 


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

def error_backtrace
  Array(error&.backtrace)
end

#error_class ⇒ String?

Error class name, when present.

Returns:

  • (String, nil) 


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

def error_class
  error&.class&.name
end

#error_message ⇒ String?

Error message, when present.

Returns:

  • (String, nil) 


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

def error_message
  error&.message
end

#failed_at ⇒ String?

Timestamp for when the failure occurred, when present.

Returns:

  • (String, nil) 


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

def failed_at
  metadata[:failed_at]
end

#failure? ⇒ Boolean

Returns true when status is :failure.

Returns:

  • (Boolean) —

    true when status is :failure



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

def failure? = status == :failure

#failure_reason ⇒ String?

Human-readable failure reason, when present.

Returns:

  • (String, nil) 


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

def failure_reason
  metadata[:reason]
end

#processor_name ⇒ String?

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

Returns:

  • (String, nil) 


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

def processor_name
  metadata[:processor]
end

#retryable? ⇒ Boolean

Whether the failure is retryable.

Returns:

  • (Boolean) 


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

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

#skipped? ⇒ Boolean

Returns true when status is :skipped.

Returns:

  • (Boolean) —

    true when status is :skipped



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

def skipped? = status == :skipped

#success? ⇒ Boolean

Returns true when status is :success.

Returns:

  • (Boolean) —

    true when status is :success



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

def success? = status == :success

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

Convert the result into a shareable hash.

Returns:

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


132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/cdc/core/processor_result.rb', line 132

def to_h
  payload = {
    'status' => status,
    'event' => event&.to_h,
    'error_class' => error_class,
    'error_message' => error_message,
    'error_backtrace' => error_backtrace,
    'metadata' => metadata.to_h
  }

  Ractor.make_shareable(payload.freeze)
end