Class: JetstreamBridge::Models::EventEnvelope

Inherits:
Object
  • Object
show all
Defined in:
lib/jetstream_bridge/models/event_envelope.rb

Overview

Immutable value object representing an event envelope.

Encapsulates all fields of a JetStream Bridge event and freezes itself (including the payload) after construction for thread-safety.

Constant Summary collapse

SCHEMA_VERSION =

Current envelope schema version

1

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(resource_type:, event_type:, payload:, event_id: nil, occurred_at: nil, trace_id: nil, producer: nil, resource_id: nil) ⇒ EventEnvelope

Build a new EventEnvelope.

Parameters:

  • resource_type (String) —

    Resource type (e.g. “user”)

  • event_type (String) —

    Event type (e.g. “created”)

  • payload (Hash) —

    Event payload data

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

    Custom event ID (auto-generated UUID if nil)

  • occurred_at (Time, String, nil) (defaults to: nil) —

    Event timestamp (defaults to now)

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

    Distributed trace ID (auto-generated if nil)

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

    Producer app name (defaults to config.app_name)

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

    Resource ID (extracted from payload if nil)

Raises:

  • (ArgumentError) —

    If required fields are blank



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 39

def initialize(
  resource_type:,
  event_type:,
  payload:,
  event_id: nil,
  occurred_at: nil,
  trace_id: nil,
  producer: nil,
  resource_id: nil
)
  @event_id = event_id || SecureRandom.uuid
  @schema_version = SCHEMA_VERSION
  @event_type = event_type.to_s
  @producer = producer || JetstreamBridge.config.app_name
  @resource_type = resource_type.to_s
  @resource_id = resource_id || extract_resource_id(payload)
  @occurred_at = parse_occurred_at(occurred_at)
  @trace_id = trace_id || SecureRandom.hex(8)
  @payload = deep_freeze(payload)

  validate!
  freeze
end

Instance Attribute Details

#event_id ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def event_id
  @event_id
end

#event_type ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def event_type
  @event_type
end

#occurred_at ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def occurred_at
  @occurred_at
end

#payload ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def payload
  @payload
end

#producer ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def producer
  @producer
end

#resource_id ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def resource_id
  @resource_id
end

#resource_type ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def resource_type
  @resource_type
end

#schema_version ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def schema_version
  @schema_version
end

#trace_id ⇒ String, ... (readonly)

Returns:

  • (String) —

    Unique event identifier (UUID)

  • (Integer) —

    Envelope schema version

  • (String) —

    Event type (e.g. “created”, “updated”)

  • (String) —

    Name of the producing application

  • (String) —

    Resource type (e.g. “user”, “order”)

  • (String) —

    Resource identifier extracted from payload

  • (Time) —

    When the event occurred

  • (String) —

    Distributed trace identifier

  • (Hash) —

    Frozen event payload



25
26
27
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 25

def trace_id
  @trace_id
end

Class Method Details

.from_h(hash) ⇒ EventEnvelope

Reconstruct an EventEnvelope from a hash (e.g. deserialized JSON).

Parameters:

  • hash (Hash) —

    String- or symbol-keyed envelope data

Returns:



88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 88

def self.from_h(hash)
  new(
    event_id: hash['event_id'] || hash[:event_id],
    event_type: hash['event_type'] || hash[:event_type],
    producer: hash['producer'] || hash[:producer],
    resource_type: hash['resource_type'] || hash[:resource_type],
    resource_id: hash['resource_id'] || hash[:resource_id],
    occurred_at: parse_time(hash['occurred_at'] || hash[:occurred_at]),
    trace_id: hash['trace_id'] || hash[:trace_id],
    payload: hash['payload'] || hash[:payload] || {}
  )
end

.parse_time(value) ⇒ Object 



155
156
157
158
159
160
161
162
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 155

def self.parse_time(value)
  return value if value.is_a?(Time)
  return Time.now.utc if value.nil?

  Time.parse(value.to_s)
rescue ArgumentError
  Time.now.utc
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



101
102
103
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 101

def ==(other)
  other.is_a?(EventEnvelope) && event_id == other.event_id
end

#hash ⇒ Object 



107
108
109
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 107

def hash
  event_id.hash
end

#to_h ⇒ Hash

Convert to hash for serialization.

Returns:

  • (Hash) —

    Envelope fields as a symbol-keyed hash



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/jetstream_bridge/models/event_envelope.rb', line 66

def to_h
  hash = {
    event_id: @event_id,
    schema_version: @schema_version,
    event_type: @event_type,
    producer: @producer,
    resource_type: @resource_type,
    occurred_at: format_time(@occurred_at),
    payload: @payload
  }

  # Only include optional fields if they have values
  hash[:resource_id] = @resource_id if @resource_id && !@resource_id.to_s.empty?
  hash[:trace_id] = @trace_id if @trace_id && !@trace_id.to_s.empty?

  hash
end