cloud_events 0.3.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7449de71a0d20b1c7fa726bbb850080c977299ebb92c3c52ecc04c3acaa65a0c
-  data.tar.gz: 60c0bfa47f39b3c4a10d12122c57d2ee2b26e75f4a82bc0622033275a5866946
+  metadata.gz: 036b0516dd1cbb3d6f2c4855809facc6edb4ac994b00355056182a704a072306
+  data.tar.gz: 4eccf559900a089b4a86ce269a30bd604dd4bcad3973ad5ffbe69735acb2a7e7
 SHA512:
-  metadata.gz: ba15c5d5fd8fd432b39a861297c57f04c659f0329783ad8a02f30c60f839836438df4371937d4d063f14bef326e45741140690be854dc2f8865c3defbb948074
-  data.tar.gz: 05cca16a9b8436a8cf7e7a23189d6873fbc322dbd177cd5d71886081a2a116d75ccb2215bc8c112a013976d769691ab0be96ab41b2d16e4acb57948c9aa7b8fc
+  metadata.gz: b0d255359ad545ec1f0898f437b2b220e72cc8766de1f59e0534c71c4863fd093b410e9350048506d8b99a22235d23aef9b9c4ca0fee757242229cdd283faaf2
+  data.tar.gz: 84a043396ad6cd11e6cd05fd7ce6bdd2993fcede29d2fc780c88419dc2bbd99d230c573b8c237f53940e033fe42449c0976e85c9842fef6dd829e798ecd4daa2

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+### v0.7.0 / 2022-01-14
+
+* HttpBinding#probable_event? returns false if the request method is GET or HEAD.
+* HttpBinding#decode_event raises NotCloudEventError if the request method is GET or HEAD. 
+* Fixed a NoMethodError if nil content was passed to the ContentType constructor.
+
+### 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? 
+* FIXED: Fixed a NoMethodError when a format declined to decode an http request 
+
+### v0.5.0 / 2021-06-28
+
+This is a significant update that provides several important spec-related and usability fixes. Some of the behavioral changes are breaking, so to preserve compatibility, new methods were added and old methods deprecated, particularly in the HttpBinding class. Additionally, the formatter interface has been simplified and expanded to support payload formatting.
+
+* CHANGED: Deprecated HttpBinding#decode_rack_env and replaced with HttpBinding#decode_event. (The old method remains for backward compatibility, but will be removed in version 1.0). The new decode_event method has the following differences:
+    * decode_event raises NotCloudEventError (rather than returning nil) if given an HTTP request that does not seem to have been intended as a CloudEvent.
+    * decode_event takes an allow_opaque argument that, when set to true, returns a CloudEvents::Event::Opaque (rather than raising an exception) if given a structured event with a format not known by the SDK. Opaque event objects cannot have their fields inspected, but can be reserialized for retransmission to another event handler.
+    * decode_event in binary content mode now parses JSON content-types and exposes the data attribute as a JSON value.
+* CHANGED: Deprecated the HttpBinding encoding entrypoints (encode_structured_content, encode_batched_content, and encode_binary_content) and replaced with a single encode_event entrypoint that handles all cases via the structured_format argument. (The old methods remain for backward compatibility, but will be removed in version 1.0). In addition, the new encode_event method has the following differences:
+    * encode_event in binary content mode now interprets a string-valued data attribute as a JSON string and serializes it (i.e. wraps it in quotes) if the data_content_type has a JSON format. This is for compatibility with the behavior of the JSON structured mode which always treats the data attribute as a JSON value if the data_content_type indicates JSON.
+* CHANGED: The JsonFormat class interface was reworked to be more generic, combine the structured and batched calls, and add calls to handle data payloads. A Format module has been added to specify the interface used by JsonFormat and future formatters. (Breaking change of internal interfaces)
+* CHANGED: Renamed HttpContentError to UnsupportedFormatError to better reflect the specific issue being reported, and to eliminate the coupling to http. The old name remains aliased to the new name, but is deprecated and will be removed in version 1.0.
+* CHANGED: If format-driven parsing (e.g. parsing a JSON document) fails, a FormatSyntaxError will be raised instead of, for example, a JSON-specific error. The lower-level parser error can still be accessed from the exception's "cause".
+* FIXED: JsonFormat now sets the datacontenttype attribute explicitly to "application/json" if it isn't otherwise set.
+
+### v0.4.0 / 2021-05-26
+
+* ADDED: ContentType can take an optional default charset 
+* FIXED: Binary HTTP format parses quoted tokens according to RFC 7230 section 3.2.6 
+* FIXED: When encoding structured events for HTTP transport, the content-type now includes the charset
+
 ### v0.3.1 / 2021-04-25
 
 * FIXED: Fixed exception when decoding from a rack source that uses InputWrapper 

data/README.md

@@ -13,7 +13,7 @@ Features:
     JSON Batch Format.
  *  Support for sending and receiving CloudEvents via HTTP Bindings.
  *  Supports the [CloudEvent 0.3](https://github.com/cloudevents/spec/tree/v0.3)
-    and [CloudEvents 1.0](https://github.com/cloudevents/spec/tree/v1.0)
+    and [CloudEvents 1.0](https://github.com/cloudevents/spec/tree/v1.0.1)
     specifications.
  *  Extensible to additional formats and protocol bindings, and future
     specification versions.
@@ -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.2"
+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.2"
+gem "cloud_events", "~> 0.6"
 ```
 
 ```ruby
@@ -69,14 +69,16 @@ require "net/http"
 require "uri"
 
 data = { message: "Hello, CloudEvents!" }
-event = CloudEvents::Event.create spec_version: "1.0",
-                                  id:           "1234-1234-1234",
-                                  source:       "/mycontext",
-                                  type:         "com.example.someevent",
-                                  data:         data
+event = CloudEvents::Event.create \
+  spec_version:      "1.0",
+  id:                "1234-1234-1234",
+  source:            "/mycontext",
+  type:              "com.example.someevent",
+  data_content_type: "application/json",
+  data:              data
 
 cloud_events_http = CloudEvents::HttpBinding.default
-headers, body = cloud_events_http.encode_binary_content event
+headers, body = cloud_events_http.encode_event event
 Net::HTTP.post URI("http://localhost:4567"), body, headers
 ```
 

data/lib/cloud_events/content_type.rb

@@ -21,16 +21,18 @@ module CloudEvents
     # Parse the given header value.
     #
     # @param string [String] Content-Type header value in RFC 2045 format
+    # @param default_charset [String] Optional. The charset to use if none is
+    #     specified. Defaults to `us-ascii`.
     #
-    def initialize string
-      @string = string
+    def initialize string, default_charset: nil
+      @string = string.to_s
       @media_type = "text"
       @subtype_base = @subtype = "plain"
       @subtype_format = nil
       @params = []
-      @charset = "us-ascii"
+      @charset = default_charset || "us-ascii"
       @error_message = nil
-      parse consume_comments string.strip
+      parse consume_comments @string.strip
       @canonical_string = "#{@media_type}/#{@subtype}" +
                           @params.map { |k, v| "; #{k}=#{maybe_quote v}" }.join
       full_freeze

data/lib/cloud_events/errors.rb

@@ -8,21 +8,53 @@ module CloudEvents
   end
 
   ##
-  # Errors indicating unsupported or incorrectly formatted HTTP content or
-  # headers.
+  # An error raised when a protocol binding was asked to decode a CloudEvent
+  # from input data, but does not believe that the data was intended to be a
+  # CloudEvent. For example, the HttpBinding might raise this exception if
+  # given a request that has neither the requisite headers for binary content
+  # mode, nor an appropriate content-type for structured content mode.
   #
-  class HttpContentError < CloudEventsError
+  class NotCloudEventError < CloudEventsError
   end
 
   ##
-  # Errors indicating an unsupported or incorrect spec version.
+  # An error raised when a protocol binding was asked to decode a CloudEvent
+  # from input data, and the data appears to be a CloudEvent, but was encoded
+  # in a format that is not supported. Some protocol bindings can be configured
+  # to return a {CloudEvents::Event::Opaque} object instead of raising this
+  # error.
+  #
+  class UnsupportedFormatError < CloudEventsError
+  end
+
+  ##
+  # An error raised when a protocol binding was asked to decode a CloudEvent
+  # from input data, and the data appears to be intended as a CloudEvent, but
+  # has unrecoverable format or syntax errors. This error _may_ have a `cause`
+  # such as a `JSON::ParserError` with additional information.
+  #
+  class FormatSyntaxError < CloudEventsError
+  end
+
+  ##
+  # An error raised when a `specversion` is set to a value not recognized or
+  # supported by the SDK.
   #
   class SpecVersionError < CloudEventsError
   end
 
   ##
-  # Errors related to CloudEvent attributes.
+  # An error raised when a malformed CloudEvents attribute is encountered,
+  # often because a required attribute is missing, or a value does not match
+  # the attribute's type specification.
   #
   class AttributeError < CloudEventsError
   end
+
+  ##
+  # Alias of UnsupportedFormatError, for backward compatibility.
+  #
+  # @deprecated Will be removed in version 1.0. Use {UnsupportedFormatError}.
+  #
+  HttpContentError = UnsupportedFormatError
 end

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/opaque.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  module Event
+    ##
+    # This object represents opaque event data that arrived in structured
+    # content mode but was not in a recognized format. It may represent a
+    # single event or a batch of events.
+    #
+    # The event data is retained in a form that can be reserialized (in a
+    # structured cotent mode in the same format) but cannot otherwise be
+    # inspected.
+    #
+    # This object is immutable, and Ractor-shareable on Ruby 3.
+    #
+    class Opaque
+      ##
+      # Create an opaque object wrapping the given content and a content type.
+      #
+      # @param content [String] The opaque serialized event data.
+      # @param content_type [CloudEvents::ContentType,nil] The content type,
+      #     or `nil` if there is no content type.
+      # @param batch [boolean] Whether this represents a batch. If set to `nil`
+      #     or not provided, the value will be inferred from the content type
+      #     if possible, or otherwise set to `nil` indicating not known.
+      #
+      def initialize content, content_type, batch: nil
+        @content = content.freeze
+        @content_type = content_type
+        if batch.nil? && content_type&.media_type == "application"
+          case content_type.subtype_base
+          when "cloudevents"
+            batch = false
+          when "cloudevents-batch"
+            batch = true
+          end
+        end
+        @batch = batch
+        freeze
+      end
+
+      ##
+      # The opaque serialized event data
+      #
+      # @return [String]
+      #
+      attr_reader :content
+
+      ##
+      # The content type, or `nil` if there is no content type.
+      #
+      # @return [CloudEvents::ContentType,nil]
+      #
+      attr_reader :content_type
+
+      ##
+      # Whether this represents a batch, or `nil` if not known.
+      #
+      # @return [boolean,nil]
+      #
+      def batch?
+        @batch
+      end
+
+      ## @private
+      def == other
+        Opaque === other &&
+          @content == other.content &&
+          @content_type == other.content_type &&
+          @batch == other.batch?
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        @content.hash ^ @content_type.hash ^ @batch.hash
+      end
+    end
+  end
+end

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/event.rb

@@ -3,7 +3,7 @@
 require "date"
 require "uri"
 
-require "cloud_events/event/field_interpreter"
+require "cloud_events/event/opaque"
 require "cloud_events/event/v0"
 require "cloud_events/event/v1"