feat: Provide data_encoded and additional data methods on the V1 event object (#67)

Full change list:

* Added `data_encoded`, `data_decoded?` and `data?` methods to CloudEvents::Event::V1, added `:data_encoded` as an input attribute, and clarified the encoding semantics of each field.
* Changed `:attributes` keyword argument in event constructors to `:set_attributes`, to avoid any possible collision with a real extension attribute name. (The old argument name is deprecated and will be removed in 1.0.)
* Fixed various inconsistencies in the data encoding behavior of JsonFormat and HttpBinding.
* Support passing a data content encoder/decoder into JsonFormat#encode_event and JsonFormat#decode_event.
* Provided TextFormat to handle media types with trivial encoding.
* Provided Format::Multi to handle checking a series of encoders/decoders.

Signed-off-by: Daniel Azuma <[email protected]>

Author: dazuma

.rubocop.yml

@@ -8,9 +8,9 @@ Metrics/BlockLength:
   Exclude:
     - "test/**/test_*.rb"
 Metrics/ClassLength:
-  Max: 250
+  Max: 300
 Metrics/ModuleLength:
-  Max: 250
+  Max: 300
 Naming/FileName:
   Exclude:
     - "examples/*/Gemfile"

README.md

@@ -47,7 +47,7 @@ require "cloud_events"
 cloud_events_http = CloudEvents::HttpBinding.default
 
 post "/" do
-  event = cloud_events_http.decode_rack_env request.env
+  event = cloud_events_http.decode_event request.env
   logger.info "Received CloudEvent: #{event.to_h}"
 end
 ```

lib/cloud_events.rb

@@ -6,6 +6,7 @@
 require "cloud_events/format"
 require "cloud_events/http_binding"
 require "cloud_events/json_format"
+require "cloud_events/text_format"
 
 ##
 # CloudEvents implementation.

lib/cloud_events/event/field_interpreter.rb

@@ -22,11 +22,11 @@ def finish_attributes
         @attributes.freeze
       end
 
-      def string keys, required: false
+      def string keys, required: false, allow_empty: false
         object keys, required: required do |value|
           case value
           when ::String
-            raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
+            raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty? && !allow_empty
             value.freeze
             [value, value]
           else
@@ -125,7 +125,7 @@ def object keys, required: false, allow_nil: false
         end
         if value == UNDEFINED
           raise AttributeError, "The #{keys.first} field is required" if required
-          return nil
+          return allow_nil ? UNDEFINED : nil
         end
         converted, raw = yield value
         @attributes[keys.first.freeze] = raw

lib/cloud_events/event/v0.rb

@@ -34,7 +34,10 @@ class 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 `attributes` argument (but not both).
+      # 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.
@@ -68,16 +71,18 @@ class V0
       # `: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.
       #
-      # @param attributes [Hash] The data and attributes, as a hash.
+      # @param set_attributes [Hash] The data and attributes, as a hash.
+      #     (Also available as `attributes` but this usage is deprecated.)
       # @param args [keywords] The data and attributes, as keyword arguments.
       #
-      def initialize attributes: nil, **args
-        interpreter = FieldInterpreter.new attributes || args
+      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"]
@@ -98,7 +103,7 @@ def initialize attributes: nil, **args
       #
       def with **changes
         attributes = @attributes.merge changes
-        V0.new attributes: attributes
+        V0.new set_attributes: attributes
       end
 
       ##

lib/cloud_events/event/v1.rb

@@ -14,10 +14,29 @@ module Event
     # This object represents a complete CloudEvent, including the event data
     # and context attributes. It supports the standard required and optional
     # attributes defined in CloudEvents V1.0, and arbitrary extension
-    # attributes. All attribute values can be obtained (in their string form)
+    # attributes.
+    #
+    # Values for most attributes can be obtained in their encoded string form
     # via the {Event::V1#[]} method. Additionally, standard attributes have
-    # their own accessor methods that may return typed objects (such as
-    # `DateTime` for the `time` attribute).
+    # their own accessor methods that may return decoded Ruby objects (such as
+    # a `DateTime` object for the `time` attribute).
+    #
+    # The `data` attribute is treated specially because it is subject to
+    # arbitrary encoding governed by the `datacontenttype` attribute. Data is
+    # expressed in two related fields: {Event::V1#data} and
+    # {Event::V1#data_encoded}. The former, `data`, _may_ be an arbitrary Ruby
+    # object representing the decoded form of the data (for example, a Hash for
+    # most JSON-formatted data.) The latter, `data_encoded`, _must_, if
+    # present, be a Ruby String object representing the encoded string or
+    # byte array form of the data.
+    #
+    # When the CloudEvents Ruby SDK encodes an event for transmission, it will
+    # use the `data_encoded` field if present. Otherwise, it will attempt to
+    # encode the `data` field using any available encoder that recognizes the
+    # content-type. Currently, text and JSON types are supported. If the type
+    # is not supported, event encoding may fail. It is thus recommended that
+    # applications provide a `data_encoded` string, if the `data` object is
+    # nontrivially encoded.
     #
     # 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
@@ -33,8 +52,13 @@ class V1
       ##
       # Create a new cloud event object with the given data and attributes.
       #
+      # ### Specifying event attributes
+      #
       # Event attributes may be presented as keyword arguments, or as a Hash
-      # passed in via the `attributes` argument (but not both).
+      # 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.
@@ -45,11 +69,15 @@ class V1
       #  *  **: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** [`Object`] - _optional_ - The "decoded" Ruby object form
+      #     of the event `data` field, if known. (e.g. a Hash representing a
+      #     JSON document)
+      #  *  **:data_encoded** [`String`] - _optional_ - The "encoded" string
+      #     form of the event `data` field, if known. This should be set along
+      #     with the `data_content_type`.
       #  *  **: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.)
+      #     {ContentType}] - _optional_ - The content-type for the encoded data
+      #     (i.e. the event `datacontenttype` field.)
       #  *  **:data_schema** (or **:dataschema**) [`String`, `URI`] -
       #     _optional_ - The event `dataschema` field.
       #  *  **:subject** [`String`] - _optional_ - The event `subject` field.
@@ -65,16 +93,63 @@ class V1
       # `: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.
       #
-      # @param attributes [Hash] The data and attributes, as a hash.
+      # ### Specifying payload data
+      #
+      # Typically you should provide _both_ the `:data` and `:data_encoded`
+      # fields, the former representing the decoded (Ruby object) form of the
+      # data, and the second providing a hint to formatters and protocol
+      # bindings for how to seralize the data. In this case, the {#data} and
+      # {#data_encoded} methods will return the corresponding values, and
+      # {#data_decoded?} will return true to indicate that {#data} represents
+      # the decoded form.
+      #
+      # If you provide _only_ the `:data` field, omitting `:data_encoded`, then
+      # the value is expected to represent the decoded (Ruby object) form of
+      # the data. The {#data} method will return this decoded value, and
+      # {#data_decoded?} will return true. The {#data_encoded} method will
+      # return nil.
+      # When serializing such an event, it will be up to the formatter or
+      # protocol binding to encode the data. This means serialization _could_
+      # fail if the formatter does not understand the data's content type.
+      # Omitting `:data_encoded` is common if the content type is JSON related
+      # (e.g. `application/json`) and the event is being encoded in JSON
+      # structured format, because the data encoding is trivial. This form can
+      # also be used when the content type is `text/*`, for which encoding is
+      # also trivial.
+      #
+      # If you provide _only_ the `:data_encoded` field, omitting `:data`, then
+      # the value is expected to represent the encoded (string) form of the
+      # data. The {#data_encoded} method will return this value. Additionally,
+      # the {#data} method will return the same _encoded_ value, and
+      # {#data_decoded?} will return false.
+      # Event objects of this form may be returned from a protocol binding when
+      # it decodes an event with a `datacontenttype` that it does not know how
+      # to interpret. Applications should query {#data_decoded?} to determine
+      # whether the {#data} method returns encoded or decoded data.
+      #
+      # If you provide _neither_ `:data` nor `:data_encoded`, the event will
+      # have no payload data. Both {#data} and {#data_encoded} will return nil,
+      # and {#data_decoded?} will return false. (Additionally, {#data?} will
+      # return false to signal the absence of any data.)
+      #
+      # @param set_attributes [Hash] The data and attributes, as a hash.
+      #     (Also available as `attributes` but this usage is deprecated.)
       # @param args [keywords] The data and attributes, as keyword arguments.
       #
-      def initialize attributes: nil, **args
-        interpreter = FieldInterpreter.new attributes || args
+      def initialize set_attributes: nil, attributes: nil, **args
+        interpreter = FieldInterpreter.new set_attributes || attributes || args
         @spec_version = interpreter.spec_version ["specversion", "spec_version"], accept: /^1(\.|$)/
         @id = interpreter.string ["id"], required: true
         @source = interpreter.uri ["source"], required: true
         @type = interpreter.string ["type"], required: true
+        @data_encoded = interpreter.string ["data_encoded"], allow_empty: true
         @data = interpreter.data_object ["data"]
+        if @data == FieldInterpreter::UNDEFINED
+          @data = @data_encoded
+          @data_decoded = false
+        else
+          @data_decoded = true
+        end
         @data_content_type = interpreter.content_type ["datacontenttype", "data_content_type"]
         @data_schema = interpreter.uri ["dataschema", "data_schema"]
         @subject = interpreter.string ["subject"]
@@ -93,8 +168,14 @@ def initialize attributes: nil, **args
       # @return [FunctionFramework::CloudEvents::Event]
       #
       def with **changes
-        attributes = @attributes.merge changes
-        V1.new attributes: attributes
+        changes = Utils.keys_to_strings changes
+        attributes = @attributes.dup
+        if changes.key?("data") || changes.key?("data_encoded")
+          attributes.delete "data"
+          attributes.delete "data_encoded"
+        end
+        attributes.merge! changes
+        V1.new set_attributes: attributes
       end
 
       ##
@@ -160,19 +241,61 @@ def to_h
       alias specversion spec_version
 
       ##
-      # The event-specific data, or `nil` if there is no data.
+      # The event `data` field, or `nil` if there is no data.
+      #
+      # This may return the data as an encoded string _or_ as a decoded Ruby
+      # object. The {#data_decoded?} method specifies whether the `data` value
+      # is decoded or encoded.
+      #
+      # In most cases, {#data} returns a decoded value, unless the event was
+      # received from a source that could not decode the content. For example,
+      # most protocol bindings understand how to decode JSON, so an event
+      # received with a {#data_content_type} of `application/json` will usually
+      # return a decoded object (usually a Hash) from {#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`.
+      # See also {#data_encoded} and {#data_decoded?}.
       #
-      # @return [Object]
+      # @return [Object] if containing decoded data
+      # @return [String] if containing encoded data
+      # @return [nil] if there is no data
       #
       attr_reader :data
 
+      ##
+      # The encoded string representation of the data, i.e. its raw form used
+      # when encoding an event for transmission. This may be `nil` if there is
+      # no data, or if the encoded form is not known.
+      #
+      # See also {#data}.
+      #
+      # @return [String,nil]
+      #
+      attr_reader :data_encoded
+
+      ##
+      # Indicates whether the {#data} field returns decoded data.
+      #
+      # @return [true] if {#data} returns a decoded Ruby object
+      # @return [false] if {#data} returns an encoded string or if the event
+      #     has no data.
+      #
+      def data_decoded?
+        @data_decoded
+      end
+
+      ##
+      # Indicates whether the data field is present. If there is no data,
+      # {#data} will return `nil`, and {#data_decoded?} will return false.
+      #
+      # Generally, if there is no data, the {#data_content_type} field should
+      # also be absent, but this is not enforced.
+      #
+      # @return [boolean]
+      #
+      def data?
+        !@data.nil? || @data_decoded
+      end
+
       ##
       # The optional `datacontenttype` field as a {CloudEvents::ContentType}
       # object, or `nil` if the field is absent.