cloud_events 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d44f430fb349c68608ecb791c8e0727c7c6cef018022a4f28c6dcb140b201d48
-  data.tar.gz: d4f1755b09f71fe1817d227666762c642de19172062a7fbdc29ec2a837a7b31e
+  metadata.gz: e30cd516cae86c634b7fd69990ba1297a5e53fa20a7c5630b69f9f356c93589e
+  data.tar.gz: d7e6447bf17e5e18ba70153106cd8d6e3f73aa2704d9854b3f5360ccf7f869f6
 SHA512:
-  metadata.gz: c0f36a2c0cf43efafbda5b94a7392e5c52ff7974df002d0051013a4db1bd809d62721499c2f0c5f1712907f72dbbea6e2280532d1ac275a0aa33e96e4094eb19
-  data.tar.gz: c18abd09d34d4e7f51ac2f327d10ae99ab7541ee2f13afa2df46c67424e40bc2e99521f64341436858c686261cdab315945173940cd467fa55bc49ead4590096
+  metadata.gz: 2d61d33ba16d60b49b98a85d5b0253751598dc166f197f41af822ded7a7a0c742ddeae4981040267ad59ee7364fd9c967f5ec92fd40d8cfd43c81528c3994de9
+  data.tar.gz: 9de42c4f1147338b8693d4bae17f1464eaa4cc4c50b8b0e3b3613c7a8659eea7a3fe17ee5583a874e42b0d17c4eead5ebb92eb2b9efd246bacb223b7c6f3deab

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+### v0.6.0 / 2021-08-23
+
+This update further clarifies and cleans up the encoding behavior of event payloads. In particular, the event object now includes explicitly encoded data in the new `data_encoded` field, and provides information on whether the existing `data` field contains an encoded or decoded form of the payload.
+
+* 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.
+
 ### v0.5.1 / 2021-06-28
 
 * ADDED: Add HttpBinding#probable_event? 

data/README.md

@@ -35,7 +35,7 @@ A simple [Sinatra](https://sinatrarb.com) app that receives CloudEvents:
 ```ruby
 # examples/server/Gemfile
 source "https://rubygems.org"
-gem "cloud_events", "~> 0.5"
+gem "cloud_events", "~> 0.6"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -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
 ```
@@ -59,7 +59,7 @@ A simple Ruby script that sends a CloudEvent:
 ```ruby
 # examples/client/Gemfile
 source "https://rubygems.org"
-gem "cloud_events", "~> 0.5"
+gem "cloud_events", "~> 0.6"
 ```
 
 ```ruby

data/lib/cloud_events.rb

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

data/lib/cloud_events/event/field_interpreter.rb

@@ -22,11 +22,11 @@ module CloudEvents
         @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 @@ module CloudEvents
         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

data/lib/cloud_events/event/v0.rb

@@ -34,7 +34,10 @@ module CloudEvents
       # 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 @@ module CloudEvents
       # `: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 using the deprecated keyword `attributes`.)
       # @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 @@ module CloudEvents
       #
       def with **changes
         attributes = @attributes.merge changes
-        V0.new attributes: attributes
+        V0.new set_attributes: attributes
       end
 
       ##

data/lib/cloud_events/event/v1.rb

@@ -14,10 +14,29 @@ module CloudEvents
     # 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 @@ module CloudEvents
       ##
       # 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 @@ module CloudEvents
       #  *  **: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 @@ module CloudEvents
       # `: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 using the deprecated keyword `attributes`.)
       # @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 @@ module CloudEvents
       # @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 @@ module CloudEvents
       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.

data/lib/cloud_events/format.rb

@@ -8,7 +8,7 @@ module CloudEvents
   # This module documents the method signatures that may be implemented by
   # formatters.
   #
-  # A formatter is an object that implenets "structured" event encoding and
+  # A formatter is an object that implements "structured" event encoding and
   # decoding strategies for a particular format (such as JSON). In general,
   # this includes four operations:
   #
@@ -182,7 +182,7 @@ module CloudEvents
     # * `:content` (String) The serialized form of the data. This might, for
     #   example, be written to an HTTP request body. Care should be taken to
     #   set the string's encoding properly. In particular, to output binary
-    #   data, the encoding should probably be set to `ASCII_8BIT`.
+    #   data, the encoding should generally be set to `ASCII_8BIT`.
     # * `:content_type` ({CloudEvents::ContentType}) The content type for the
     #   output. This might, for example, be written to the `Content-Type`
     #   header of an HTTP request.
@@ -198,5 +198,80 @@ module CloudEvents
     def encode_data **_kwargs
       nil
     end
+
+    ##
+    # A convenience formatter that checks multiple formats for one capable of
+    # handling the given input.
+    #
+    class Multi
+      ##
+      # Create a multi format.
+      #
+      # @param formats [Array<Format>] An array of formats to check in order
+      # @param result_checker [Proc] An optional block that determines whether
+      #     a result provided by a format is acceptable. The block takes the
+      #     format's result as an argument, and returns either the result to
+      #     indicate acceptability, or `nil` to indicate not.
+      #
+      def initialize formats = [], &result_checker
+        @formats = formats
+        @result_checker = result_checker
+      end
+
+      ##
+      # The formats to check, in order.
+      #
+      # @return [Array<Format>]
+      #
+      attr_reader :formats
+
+      ##
+      # Implements {Format#decode_event}
+      #
+      def decode_event **kwargs
+        @formats.each do |elem|
+          result = elem.decode_event(**kwargs)
+          result = @result_checker.call result if @result_checker
+          return result if result
+        end
+        nil
+      end
+
+      ##
+      # Implements {Format#encode_event}
+      #
+      def encode_event **kwargs
+        @formats.each do |elem|
+          result = elem.encode_event(**kwargs)
+          result = @result_checker.call result if @result_checker
+          return result if result
+        end
+        nil
+      end
+
+      ##
+      # Implements {Format#decode_data}
+      #
+      def decode_data **kwargs
+        @formats.each do |elem|
+          result = elem.decode_data(**kwargs)
+          result = @result_checker.call result if @result_checker
+          return result if result
+        end
+        nil
+      end
+
+      ##
+      # Implements {Format#encode_data}
+      #
+      def encode_data **kwargs
+        @formats.each do |elem|
+          result = elem.encode_data(**kwargs)
+          result = @result_checker.call result if @result_checker
+          return result if result
+        end
+        nil
+      end
+    end
   end
 end

data/lib/cloud_events/http_binding.rb

@@ -28,7 +28,7 @@ module CloudEvents
     def self.default
       @default ||= begin
         http_binding = new
-        http_binding.register_formatter JsonFormat.new, JSON_FORMAT
+        http_binding.register_formatter JsonFormat.new, encoder_name: JSON_FORMAT
         http_binding.default_encoder_name = JSON_FORMAT
         http_binding
       end
@@ -38,10 +38,20 @@ module CloudEvents
     # Create an empty HTTP binding.
     #
     def initialize
-      @event_decoders = []
+      @event_decoders = Format::Multi.new do |result|
+        result&.key?(:event) || result&.key?(:event_batch) ? result : nil
+      end
       @event_encoders = {}
-      @data_decoders = [DefaultDataFormat]
-      @data_encoders = [DefaultDataFormat]
+      @data_decoders = Format::Multi.new do |result|
+        result&.key?(:data) && result&.key?(:content_type) ? result : nil
+      end
+      @data_encoders = Format::Multi.new do |result|
+        result&.key?(:content) && result&.key?(:content_type) ? result : nil
+      end
+      text_format = TextFormat.new
+      @data_decoders.formats.replace [text_format, DefaultDataFormat]
+      @data_encoders.formats.replace [text_format, DefaultDataFormat]
+
       @default_encoder_name = nil
     end
 
@@ -51,15 +61,18 @@ module CloudEvents
     # {CloudEvents::Format} for a list of possible methods.
     #
     # @param formatter [Object] The formatter
-    # @param name [String] The encoder name under which this formatter will
-    #     register its encode operations. Optional. If not specified, any event
-    #     encoder will _not_ be registered.
+    # @param encoder_name [String] The encoder name under which this formatter
+    #     will register its encode operations. Optional. If not specified, any
+    #     event encoder will _not_ be registered.
+    # @param deprecated_name [String] This positional argument is deprecated
+    #     and will be removed in version 1.0. Use encoder_name instead.
     # @return [self]
     #
-    def register_formatter formatter, name = nil
-      name = name.to_s.strip.downcase if name
+    def register_formatter formatter, deprecated_name = nil, encoder_name: nil
+      encoder_name ||= deprecated_name
+      encoder_name = encoder_name.to_s.strip.downcase if encoder_name
       decode_event = formatter.respond_to? :decode_event
-      encode_event = name if formatter.respond_to? :encode_event
+      encode_event = encoder_name if formatter.respond_to? :encode_event
       decode_data = formatter.respond_to? :decode_data
       encode_data = formatter.respond_to? :encode_data
       register_formatter_methods formatter,
@@ -91,18 +104,21 @@ module CloudEvents
                                    encode_event: nil,
                                    decode_data: false,
                                    encode_data: false
-      @event_decoders << formatter if decode_event
+      @event_decoders.formats.unshift formatter if decode_event
       if encode_event
-        formatters = @event_encoders[encode_event] ||= []
-        formatters << formatter unless formatters.include? formatter
+        encoders = @event_encoders[encode_event] ||= Format::Multi.new do |result|
+          result&.key?(:content) && result&.key?(:content_type) ? result : nil
+        end
+        encoders.formats.unshift formatter
       end
-      @data_decoders << formatter if decode_data
-      @data_encoders << formatter if encode_data
+      @data_decoders.formats.unshift formatter if decode_data
+      @data_encoders.formats.unshift formatter if encode_data
       self
     end
 
     ##
     # The name of the encoder to use if none is specified
+    #
     # @return [String,nil]
     #
     attr_accessor :default_encoder_name
@@ -150,7 +166,7 @@ module CloudEvents
       content_type_string = env["CONTENT_TYPE"]
       content_type = ContentType.new content_type_string if content_type_string
       content = read_with_charset env["rack.input"], content_type&.charset
-      result = decode_binary_content(content, content_type, env) ||
+      result = decode_binary_content(content, content_type, env, false, **format_args) ||
                decode_structured_content(content, content_type, allow_opaque, **format_args)
       if result.nil?
         content_type_string = content_type_string ? content_type_string.inspect : "not present"
@@ -226,7 +242,7 @@ module CloudEvents
       content_type = ContentType.new content_type_string if content_type_string
       content = read_with_charset env["rack.input"], content_type&.charset
       env["rack.input"].rewind rescue nil
-      decode_binary_content(content, content_type, env, legacy_data_decode: true) ||
+      decode_binary_content(content, content_type, env, true, **format_args) ||
         decode_structured_content(content, content_type, false, **format_args)
     end
 
@@ -241,12 +257,10 @@ module CloudEvents
     # @return [Array(headers,String)]
     #
     def encode_structured_content event, format_name, **format_args
-      Array(@event_encoders[format_name]).reverse_each do |handler|
-        result = handler.encode_event event: event, **format_args
-        if result&.key?(:content) && result&.key?(:content_type)
-          return [{ "Content-Type" => result[:content_type].to_s }, result[:content]]
-        end
-      end
+      result = @event_encoders[format_name]&.encode_event event: event,
+                                                          data_encoder: @data_encoders,
+                                                          **format_args
+      return [{ "Content-Type" => result[:content_type].to_s }, result[:content]] if result
       raise ::ArgumentError, "Unknown format name: #{format_name.inspect}"
     end
 
@@ -261,12 +275,10 @@ module CloudEvents
     # @return [Array(headers,String)]
     #
     def encode_batched_content event_batch, format_name, **format_args
-      Array(@event_encoders[format_name]).reverse_each do |handler|
-        result = handler.encode_event event_batch: event_batch, **format_args
-        if result&.key?(:content) && result&.key?(:content_type)
-          return [{ "Content-Type" => result[:content_type].to_s }, result[:content]]
-        end
-      end
+      result = @event_encoders[format_name]&.encode_event event_batch: event_batch,
+                                                          data_encoder: @data_encoders,
+                                                          **format_args
+      return [{ "Content-Type" => result[:content_type].to_s }, result[:content]] if result
       raise ::ArgumentError, "Unknown format name: #{format_name.inspect}"
     end
 
@@ -282,25 +294,16 @@ module CloudEvents
     def encode_binary_content event, legacy_data_encode: true, **format_args
       headers = {}
       event.to_h.each do |key, value|
-        unless ["data", "datacontenttype"].include? key
+        unless ["data", "data_encoded", "datacontenttype"].include? key
           headers["CE-#{key}"] = percent_encode value
         end
       end
-      if legacy_data_encode
-        body = event.data
-        content_type = event.data_content_type&.to_s
-        case body
-        when ::String
-          content_type ||= string_content_type body
-        when nil
-          content_type = nil
+      body, content_type =
+        if legacy_data_encode || event.spec_version.start_with?("0.")
+          legacy_extract_event_data event
         else
-          body = ::JSON.dump body
-          content_type ||= "application/json; charset=#{body.encoding.name.downcase}"
+          normal_extract_event_data event, format_args
         end
-      else
-        body, content_type = encode_data event.spec_version, event.data, event.data_content_type, **format_args
-      end
       headers["Content-Type"] = content_type.to_s if content_type
       [headers, body]
     end
@@ -353,7 +356,7 @@ module CloudEvents
     def add_named_formatter collection, formatter, name
       return unless name
       formatters = collection[name] ||= []
-      formatters << formatter unless formatters.include? formatter
+      formatters.unshift formatter unless formatters.include? formatter
     end
 
     ##
@@ -361,11 +364,11 @@ module CloudEvents
     # structured mode.
     #
     def decode_structured_content content, content_type, allow_opaque, **format_args
-      @event_decoders.reverse_each do |decoder|
-        result = decoder.decode_event content: content, content_type: content_type, **format_args
-        event = result[:event] || result[:event_batch] if result
-        return event if event
-      end
+      result = @event_decoders.decode_event content: content,
+                                            content_type: content_type,
+                                            data_decoder: @data_decoders,
+                                            **format_args
+      return result[:event] || result[:event_batch] if result
       if content_type&.media_type == "application" &&
          ["cloudevents", "cloudevents-batch"].include?(content_type.subtype_base)
         return Event::Opaque.new content, content_type if allow_opaque
@@ -380,19 +383,41 @@ module CloudEvents
     # TODO: legacy_data_decode is deprecated and can be removed when
     # decode_rack_env is removed.
     #
-    def decode_binary_content content, content_type, env, legacy_data_decode: false
+    def decode_binary_content content, content_type, env, legacy_data_decode, **format_args
       spec_version = env["HTTP_CE_SPECVERSION"]
       return nil unless spec_version
       unless spec_version =~ /^0\.3|1(\.|$)/
         raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
-      if legacy_data_decode
-        data = content
+      attributes = { "spec_version" => spec_version }
+      if legacy_data_decode || spec_version.start_with?("0.")
+        legacy_populate_data_attributes attributes, content, content_type
       else
-        data, content_type = decode_data spec_version, content, content_type
+        normal_populate_data_attributes attributes, content, content_type, spec_version, format_args
+      end
+      populate_attributes_from_env attributes, env
+      Event.create spec_version: spec_version, set_attributes: attributes
+    end
+
+    def legacy_populate_data_attributes attributes, content, content_type
+      attributes["data"] = content
+      attributes["data_content_type"] = content_type if content_type
+    end
+
+    def normal_populate_data_attributes attributes, content, content_type, spec_version, format_args
+      attributes["data_encoded"] = content
+      result = @data_decoders.decode_data spec_version: spec_version,
+                                          content: content,
+                                          content_type: content_type,
+                                          **format_args
+      if result
+        attributes["data"] = result[:data]
+        content_type = result[:content_type]
       end
-      attributes = { "spec_version" => spec_version, "data" => data }
       attributes["data_content_type"] = content_type if content_type
+    end
+
+    def populate_attributes_from_env attributes, env
       omit_names = ["specversion", "spec_version", "data", "datacontenttype", "data_content_type"]
       env.each do |key, value|
         match = /^HTTP_CE_(\w+)$/.match key
@@ -400,33 +425,35 @@ module CloudEvents
         attr_name = match[1].downcase
         attributes[attr_name] = percent_decode value unless omit_names.include? attr_name
       end
-      Event.create spec_version: spec_version, attributes: attributes
     end
 
-    def decode_data spec_version, content, content_type, **format_args
-      @data_decoders.reverse_each do |handler|
-        result = handler.decode_data spec_version: spec_version,
-                                     content: content,
-                                     content_type: content_type,
-                                     **format_args
-        if result&.key?(:data) && result&.key?(:content_type)
-          return [result[:data], result[:content_type]]
-        end
+    def legacy_extract_event_data event
+      body = event.data
+      content_type = event.data_content_type&.to_s
+      case body
+      when ::String
+        [body, content_type || string_content_type(body)]
+      when nil
+        [nil, nil]
+      else
+        [::JSON.dump(body), content_type || "application/json; charset=#{body.encoding.name.downcase}"]
       end
-      raise "Should not get here"
     end
 
-    def encode_data spec_version, data_obj, content_type, **format_args
-      @data_encoders.reverse_each do |handler|
-        result = handler.encode_data spec_version: spec_version,
-                                     data: data_obj,
-                                     content_type: content_type,
-                                     **format_args
-        if result&.key?(:content) && result&.key?(:content_type)
-          return [result[:content], result[:content_type]]
-        end
+    def normal_extract_event_data event, format_args
+      body = event.data_encoded
+      if body
+        [body, event.data_content_type]
+      elsif event.data?
+        result = @data_encoders.encode_data spec_version: event.spec_version,
+                                            data: event.data,
+                                            content_type: event.data_content_type,
+                                            **format_args
+        raise UnsupportedFormatError, "Could not encode unknown content-type: #{content_type}" unless result
+        [result[:content], result[:content_type]]
+      else
+        ["", nil]
       end
-      raise "Should not get here"
     end
 
     def read_with_charset io, charset
@@ -447,19 +474,14 @@ module CloudEvents
     module DefaultDataFormat
       # @private
       def self.decode_data content: nil, content_type: nil, **_extra_kwargs
-        { data: content, content_type: content_type }
+        return nil unless content_type.nil?
+        { data: content, content_type: nil }
       end
 
       # @private
       def self.encode_data data: nil, content_type: nil, **_extra_kwargs
-        content = data.to_s
-        content_type ||=
-          if content.encoding == ::Encoding::ASCII_8BIT
-            "application/octet-stream"
-          else
-            "text/plain; charset=#{content.encoding.name.downcase}"
-          end
-        { content: content, content_type: content_type }
+        return nil unless content_type.nil?
+        { content: data.to_s, content_type: nil }
       end
     end
   end

data/lib/cloud_events/json_format.rb

@@ -30,22 +30,24 @@ module CloudEvents
     #
     # @param content [String] Serialized content to decode.
     # @param content_type [CloudEvents::ContentType] The input content type.
+    # @param data_decoder [#decode_data] Optional data field decoder, used for
+    #     non-JSON content types.
     # @return [Hash] if accepting the request.
     # @return [nil] if declining the request.
     # @raise [CloudEvents::FormatSyntaxError] if the JSON could not be parsed
     # @raise [CloudEvents::SpecVersionError] if an unsupported specversion is
     #     found.
     #
-    def decode_event content: nil, content_type: nil, **_other_kwargs
+    def decode_event content: nil, content_type: nil, data_decoder: nil, **_other_kwargs
       return nil unless content && content_type&.media_type == "application" && content_type&.subtype_format == "json"
       case content_type.subtype_base
       when "cloudevents"
-        event = decode_hash_structure ::JSON.parse(content), charset_of(content)
+        event = decode_hash_structure ::JSON.parse(content), charset: charset_of(content), data_decoder: data_decoder
         { event: event }
       when "cloudevents-batch"
         charset = charset_of content
         batch = Array(::JSON.parse(content)).map do |structure|
-          decode_hash_structure structure, charset
+          decode_hash_structure structure, charset: charset, data_decoder: data_decoder
         end
         { event_batch: batch }
       end
@@ -69,18 +71,21 @@ module CloudEvents
     #
     # @param event [CloudEvents::Event] An event to encode.
     # @param event_batch [Array<CloudEvents::Event>] An event batch to encode.
+    # @param data_encoder [#encode_data] Optional data field encoder, used for
+    #     non-JSON content types.
     # @param sort [boolean] Whether to sort keys of the JSON output.
     # @return [Hash] if accepting the request.
     # @return [nil] if declining the request.
+    # @raise [CloudEvents::FormatSyntaxError] if the JSON could not be parsed
     #
-    def encode_event event: nil, event_batch: nil, sort: false, **_other_kwargs
+    def encode_event event: nil, event_batch: nil, data_encoder: nil, sort: false, **_other_kwargs
       if event && !event_batch
-        structure = encode_hash_structure event
+        structure = encode_hash_structure event, data_encoder: data_encoder
         structure = sort_keys structure if sort
         subtype = "cloudevents"
       elsif event_batch && !event
         structure = event_batch.map do |elem|
-          structure_elem = encode_hash_structure elem
+          structure_elem = encode_hash_structure elem, data_encoder: data_encoder
           sort ? sort_keys(structure_elem) : structure_elem
         end
         subtype = "cloudevents-batch"
@@ -90,6 +95,8 @@ module CloudEvents
       content = ::JSON.dump structure
       content_type = ContentType.new "application/#{subtype}+json; charset=#{charset_of content}"
       { content: content, content_type: content_type }
+    rescue ::JSON::JSONError
+      raise FormatSyntaxError, "JSON syntax error"
     end
 
     ##
@@ -116,7 +123,7 @@ module CloudEvents
     def decode_data spec_version: nil, content: nil, content_type: nil, **_other_kwargs
       return nil unless spec_version
       return nil unless content
-      return nil unless content_type&.subtype_base == "json" || content_type&.subtype_format == "json"
+      return nil unless json_content_type? content_type
       unless spec_version =~ /^0\.3|1(\.|$)/
         raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
@@ -151,7 +158,7 @@ module CloudEvents
     def encode_data spec_version: nil, data: UNSPECIFIED, content_type: nil, sort: false, **_other_kwargs
       return nil unless spec_version
       return nil if data == UNSPECIFIED
-      return nil unless content_type&.subtype_base == "json" || content_type&.subtype_format == "json"
+      return nil unless json_content_type? content_type
       unless spec_version =~ /^0\.3|1(\.|$)/
         raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
@@ -164,19 +171,20 @@ module CloudEvents
     # Decode a single event from a hash data structure with keys and types
     # conforming to the JSON envelope.
     #
-    # @private
-    #
     # @param structure [Hash] An input hash.
-    # @param charset [String] The charset.
+    # @param charset [String] The charset of the original encoded JSON document
+    #     if known. Used to provide default content types.
+    # @param data_decoder [#decode_data] Optional data field decoder, used for
+    #     non-JSON content types.
     # @return [CloudEvents::Event]
     #
-    def decode_hash_structure structure, charset = nil
+    def decode_hash_structure structure, charset: nil, data_decoder: nil
       spec_version = structure["specversion"].to_s
       case spec_version
       when "0.3"
         decode_hash_structure_v0 structure, charset
       when /^1(\.|$)/
-        decode_hash_structure_v1 structure, charset
+        decode_hash_structure_v1 structure, charset, spec_version, data_decoder
       else
         raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
@@ -186,24 +194,28 @@ module CloudEvents
     # Encode a single event to a hash data structure with keys and types
     # conforming to the JSON envelope.
     #
-    # @private
-    #
     # @param event [CloudEvents::Event] An input event.
+    # @param data_encoder [#encode_data] Optional data field encoder, used for
+    #     non-JSON content types.
     # @return [String] The hash structure.
     #
-    def encode_hash_structure event
+    def encode_hash_structure event, data_encoder: nil
       case event
       when Event::V0
         encode_hash_structure_v0 event
       when Event::V1
-        encode_hash_structure_v1 event
+        encode_hash_structure_v1 event, data_encoder
       else
-        raise SpecVersionError, "Unrecognized specversion: #{event.spec_version}"
+        raise SpecVersionError, "Unrecognized event type: #{event.class}"
       end
     end
 
     private
 
+    def json_content_type? content_type
+      content_type&.subtype_base == "json" || content_type&.subtype_format == "json"
+    end
+
     def sort_keys obj
       return obj unless obj.is_a? ::Hash
       result = {}
@@ -232,18 +244,43 @@ module CloudEvents
       Event::V0.new attributes: structure
     end
 
-    def decode_hash_structure_v1 structure, charset
+    def decode_hash_structure_v1 structure, charset, spec_version, data_decoder
+      unless structure.key?("data") || structure.key?("data_base64")
+        return Event::V1.new set_attributes: structure
+      end
+      structure = structure.dup
+      content, content_type = retrieve_content_from_data_fields structure, charset
+      populate_data_fields_from_content structure, content, content_type, spec_version, data_decoder
+      Event::V1.new set_attributes: structure
+    end
+
+    def retrieve_content_from_data_fields structure, charset
       if structure.key? "data_base64"
-        structure = structure.dup
-        structure["data"] = ::Base64.decode64 structure.delete "data_base64"
-        structure["datacontenttype"] ||= "application/octet-stream"
-      elsif !structure.key? "datacontenttype"
-        structure = structure.dup
-        content_type = "application/json"
-        content_type = "#{content_type}; charset=#{charset}" if charset
-        structure["datacontenttype"] = content_type
+        content = ::Base64.decode64 structure.delete "data_base64"
+        content_type = structure["datacontenttype"] || "application/octet-stream"
+      else
+        content = structure["data"]
+        content_type = structure["datacontenttype"]
+        content_type ||= charset ? "application/json; charset=#{charset}" : "application/json"
+      end
+      [content, ContentType.new(content_type)]
+    end
+
+    def populate_data_fields_from_content structure, content, content_type, spec_version, data_decoder
+      if json_content_type? content_type
+        structure["data_encoded"] = ::JSON.dump content
+        structure["data"] = content
+      else
+        structure["data_encoded"] = content = content.to_s
+        result = data_decoder&.decode_data spec_version: spec_version, content: content, content_type: content_type
+        if result
+          structure["data"] = result[:data]
+          content_type = result[:content_type]
+        else
+          structure.delete "data"
+        end
       end
-      Event::V1.new attributes: structure
+      structure["datacontenttype"] = content_type
     end
 
     def encode_hash_structure_v0 event
@@ -252,17 +289,40 @@ module CloudEvents
       structure
     end
 
-    def encode_hash_structure_v1 event
+    def encode_hash_structure_v1 event, data_encoder
       structure = event.to_h
-      data = structure["data"]
-      if data.is_a?(::String) && data.encoding == ::Encoding::ASCII_8BIT
-        structure.delete "data"
-        structure["data_base64"] = ::Base64.encode64 data
-        structure["datacontenttype"] ||= "application/octet-stream"
+      return structure unless structure.key?("data") || structure.key?("data_encoded")
+      content_type = event.data_content_type
+      if content_type.nil? || json_content_type?(content_type)
+        encode_data_fields_for_json_content structure, event
       else
-        structure["datacontenttype"] ||= "application/json"
+        encode_data_fields_for_other_content structure, event, data_encoder
       end
       structure
     end
+
+    def encode_data_fields_for_json_content structure, event
+      structure["data"] = ::JSON.parse event.data unless event.data_decoded?
+      structure.delete "data_encoded"
+      structure["datacontenttype"] ||= "application/json"
+    end
+
+    def encode_data_fields_for_other_content structure, event, data_encoder
+      data_encoded = structure.delete "data_encoded"
+      unless data_encoded
+        result = data_encoder&.encode_data spec_version: event.spec_version,
+                                           data: event.data,
+                                           content_type: event.data_content_type
+        raise UnsupportedFormatError, "Unable to encode data of media type #{event.data_content_type}" unless result
+        data_encoded = result[:content]
+        structure["datacontenttype"] = result[:content_type].to_s
+      end
+      if data_encoded.encoding == ::Encoding::ASCII_8BIT
+        structure["data_base64"] = ::Base64.encode64 data_encoded
+        structure.delete "data"
+      else
+        structure["data"] = data_encoded
+      end
+    end
   end
 end

data/lib/cloud_events/text_format.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module CloudEvents
+  ##
+  # An data encoder/decoder for text content types. This handles any media type
+  # of the form `text/*` or `application/octet-stream`, and passes strings
+  # through as-is.
+  #
+  class TextFormat
+    # @private
+    UNSPECIFIED = ::Object.new.freeze
+
+    ##
+    # Trivially decode an event data string using text format.
+    # See {CloudEvents::Format#decode_data} for a general description.
+    #
+    # Expects `:content` and `:content_type` arguments, and will decline the
+    # request unless all three are provided.
+    #
+    # If decoding succeeded, returns a hash with the following keys:
+    #
+    # * `:data` (Object) The payload object to set as the `data` attribute.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type to be set
+    #   as the `datacontenttype` attribute.
+    #
+    # @param content [String] Serialized content to decode.
+    # @param content_type [CloudEvents::ContentType] The input content type.
+    # @return [Hash] if accepting the request.
+    # @return [nil] if declining the request.
+    #
+    def decode_data content: nil, content_type: nil, **_other_kwargs
+      return nil unless content
+      return nil unless text_content_type? content_type
+      { data: content.to_s, content_type: content_type }
+    end
+
+    ##
+    # Trivially an event data object using text format.
+    # See {CloudEvents::Format#encode_data} for a general description.
+    #
+    # Expects `:data` and `:content_type` arguments, and will decline the
+    # request unless all three are provided.
+    # The `:data` object will be converted to a string if it is not already a
+    # string.
+    #
+    # If decoding succeeded, returns a hash with the following keys:
+    #
+    # * `:content` (String) The serialized form of the data.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type for the
+    #   output.
+    #
+    # @param data [Object] A data object to encode.
+    # @param content_type [CloudEvents::ContentType] The input content type
+    # @return [Hash] if accepting the request.
+    # @return [nil] if declining the request.
+    #
+    def encode_data data: UNSPECIFIED, content_type: nil, **_other_kwargs
+      return nil if data == UNSPECIFIED
+      return nil unless text_content_type? content_type
+      { content: data.to_s, content_type: content_type }
+    end
+
+    private
+
+    def text_content_type? content_type
+      content_type&.media_type == "text" ||
+        content_type&.media_type == "application" && content_type&.subtype == "octet-stream"
+    end
+  end
+end

data/lib/cloud_events/version.rb

@@ -5,5 +5,5 @@ module CloudEvents
   # Version of the Ruby CloudEvents SDK
   # @return [String]
   #
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cloud_events
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-28 00:00:00.000000000 Z
+date: 2021-08-23 00:00:00.000000000 Z
 dependencies: []
 description: The official Ruby implementation of the CloudEvents Specification. Provides
   data types for events, and HTTP/JSON bindings for marshalling and unmarshalling
@@ -35,15 +35,16 @@ files:
 - lib/cloud_events/format.rb
 - lib/cloud_events/http_binding.rb
 - lib/cloud_events/json_format.rb
+- lib/cloud_events/text_format.rb
 - lib/cloud_events/version.rb
 homepage: https://github.com/cloudevents/sdk-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://cloudevents.github.io/sdk-ruby/v0.5.1/file.CHANGELOG.html
+  changelog_uri: https://cloudevents.github.io/sdk-ruby/v0.6.0/file.CHANGELOG.html
   source_code_uri: https://github.com/cloudevents/sdk-ruby
   bug_tracker_uri: https://github.com/cloudevents/sdk-ruby/issues
-  documentation_uri: https://cloudevents.github.io/sdk-ruby/v0.5.1
+  documentation_uri: https://cloudevents.github.io/sdk-ruby/v0.6.0
 post_install_message: 
 rdoc_options: []
 require_paths: