Class: CloudEvents::Event::V0

Inherits:
Object
  • Object
show all
Includes:
CloudEvents::Event
Defined in:
lib/cloud_events/event/v0.rb

Overview

A CloudEvents V0 data type.

This object represents a complete CloudEvent, including the event data and context attributes. It supports the standard required and optional attributes defined in CloudEvents V0.3, and arbitrary extension attributes. All attribute values can be obtained (in their string form) via the #[] method. Additionally, standard attributes have their own accessor methods that may return typed objects (such as DateTime for the time attribute).

This object is immutable, and Ractor-shareable on Ruby 3. The data and attribute values can be retrieved but not modified. To obtain an event with modifications, use the #with method to create a copy with the desired changes.

See https://github.com/cloudevents/spec/blob/v0.3/spec.md for descriptions of the standard attributes.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from CloudEvents::Event

create

Constructor Details

#initialize(set_attributes: nil, attributes: nil, **args) ⇒ V0

Create a new cloud event object with the given data and attributes.

Event attributes may be presented as keyword arguments, or as a Hash passed in via the special :set_attributes keyword argument (but not both). The :set_attributes keyword argument is useful for passing in attributes whose keys are strings rather than symbols, which some versions of Ruby will not accept as keyword arguments.

The following standard attributes are supported and exposed as attribute methods on the object.

  • :spec_version (or :specversion) [String] - required - The CloudEvents spec version (i.e. the specversion field.)
  • :id [String] - required - The event id field.
  • :source [String, URI] - required - The event source field.
  • :type [String] - required - The event type field.
  • :data [Object] - optional - The data associated with the event (i.e. the data field).
  • :data_content_encoding (or :datacontentencoding) [String] - optional - The content-encoding for the data (i.e. the datacontentencoding field.)
  • :data_content_type (or :datacontenttype) [String, ContentType] - optional - The content-type for the data, if the data is a string (i.e. the event datacontenttype field.)
  • :schema_url (or :schemaurl) [String, URI] - optional - The event schemaurl field.
  • :subject [String] - optional - The event subject field.
  • :time [String, DateTime, Time] - optional - The event time field.

Any additional attributes are assumed to be extension attributes. They are not available as separate methods, but can be accessed via the CloudEvents::Event::V1#[] operator.

Note that attribute objects passed in may get deep-frozen if they are used in the final event object. This is particularly important for the :data field, for example if you pass a structured hash. If this is an issue, make a deep copy of objects before passing to this constructor.

Parameters:

  • set_attributes (Hash) (defaults to: nil) —

    The data and attributes, as a hash. (Also available using the deprecated keyword attributes.)

  • args (keywords) —

    The data and attributes, as keyword arguments.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/cloud_events/event/v0.rb', line 78

def initialize(set_attributes: nil, attributes: nil, **args)
  interpreter = FieldInterpreter.new(set_attributes || attributes || args)
  @spec_version = interpreter.spec_version(["specversion", "spec_version"], accept: /^0\.3$/)
  @id = interpreter.string(["id"], required: true)
  @source = interpreter.uri(["source"], required: true)
  @type = interpreter.string(["type"], required: true)
  @data = interpreter.data_object(["data"])
  @data = nil if @data == FieldInterpreter::UNDEFINED
  @data_content_encoding = interpreter.string(["datacontentencoding", "data_content_encoding"])
  @data_content_type = interpreter.content_type(["datacontenttype", "data_content_type"])
  @schema_url = interpreter.uri(["schemaurl", "schema_url"])
  @subject = interpreter.string(["subject"])
  @time = interpreter.rfc3339_date_time(["time"])
  @attributes = interpreter.finish_attributes(requires_lc_start: true)
  freeze
end

Instance Attribute Details

#data ⇒ Object (readonly)

The event-specific data, or nil if there is no data.

Data may be one of the following types:

  • Binary data, represented by a String using the ASCII-8BIT encoding.
  • A string in some other encoding such as UTF-8 or US-ASCII.
  • Any JSON data type, such as a Boolean, Integer, Array, Hash, or nil.

Returns:

  • (Object) 


183
184
185
 
# File 'lib/cloud_events/event/v0.rb', line 183

def data
  @data
end

#data_content_encoding ⇒ String? (readonly) Also known as: datacontentencoding

The optional datacontentencoding field as a String object, or nil if the field is absent.

Returns:

  • (String, nil) 


191
192
193
 
# File 'lib/cloud_events/event/v0.rb', line 191

def data_content_encoding
  @data_content_encoding
end

#data_content_type ⇒ CloudEvents::ContentType? (readonly) Also known as: datacontenttype

The optional datacontenttype field as a ContentType object, or nil if the field is absent.

Returns:



200
201
202
 
# File 'lib/cloud_events/event/v0.rb', line 200

def data_content_type
  @data_content_type
end

#id ⇒ String (readonly)

The id field. Required.

Returns:

  • (String) 


147
148
149
 
# File 'lib/cloud_events/event/v0.rb', line 147

def id
  @id
end

#schema_url ⇒ URI? (readonly) Also known as: schemaurl

The optional schemaurl field as a URI object, or nil if the field is absent.

Returns:

  • (URI, nil) 


209
210
211
 
# File 'lib/cloud_events/event/v0.rb', line 209

def schema_url
  @schema_url
end

#source ⇒ URI (readonly)

The source field as a URI object. Required.

Returns:

  • (URI) 


154
155
156
 
# File 'lib/cloud_events/event/v0.rb', line 154

def source
  @source
end

#spec_version ⇒ String (readonly) Also known as: specversion

The specversion field. Required.

Returns:

  • (String) 


168
169
170
 
# File 'lib/cloud_events/event/v0.rb', line 168

def spec_version
  @spec_version
end

#subject ⇒ String? (readonly)

The optional subject field, or nil if the field is absent.

Returns:

  • (String, nil) 


217
218
219
 
# File 'lib/cloud_events/event/v0.rb', line 217

def subject
  @subject
end

#time ⇒ DateTime? (readonly)

The optional time field as a DateTime object, or nil if the field is absent.

Returns:

  • (DateTime, nil) 


225
226
227
 
# File 'lib/cloud_events/event/v0.rb', line 225

def time
  @time
end

#type ⇒ String (readonly)

The type field. Required.

Returns:

  • (String) 


161
162
163
 
# File 'lib/cloud_events/event/v0.rb', line 161

def type
  @type
end

Instance Method Details

#[](key) ⇒ String?

Return the value of the given named attribute. Both standard and extension attributes are supported.

Attribute names must be given as defined in the standard CloudEvents specification. For example specversion rather than spec_version.

Results are given in their "raw" form, generally a string. This may be different from the Ruby object returned from corresponding attribute methods. For example:

event["time"]     # => String rfc3339 representation
event.time        # => DateTime object

Results are also always frozen and cannot be modified in place.

Parameters:

  • key (String, Symbol) —

    The attribute name.

Returns:

  • (String, nil) 


128
129
130
 
# File 'lib/cloud_events/event/v0.rb', line 128

def [](key)
  @attributes[key.to_s]
end

#to_h ⇒ Hash

Return a hash representation of this event. The returned hash is an unfrozen deep copy. Modifications do not affect the original event.

Returns:

  • (Hash) 


138
139
140
 
# File 'lib/cloud_events/event/v0.rb', line 138

def to_h
  Utils.deep_dup(@attributes)
end

#with(**changes) ⇒ FunctionFramework::CloudEvents::Event

Create and return a copy of this event with the given changes. See the constructor for the parameters that can be passed. In general, you can pass a new value for any attribute, or pass nil to remove an optional attribute.

Parameters:

  • changes (keywords) —

    See #initialize for a list of arguments.

Returns:

  • (FunctionFramework::CloudEvents::Event) 


104
105
106
107
 
# File 'lib/cloud_events/event/v0.rb', line 104

def with(**changes)
  attributes = @attributes.merge(changes)
  V0.new(set_attributes: attributes)
end