feat!: Decode returns opaque event objects when a formatter is not available (#58)

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

Author: dazuma

.rubocop.yml

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

lib/cloud_events/content_type.rb

@@ -25,7 +25,7 @@ class ContentType
     #     specified. Defaults to `us-ascii`.
     #
     def initialize string, default_charset: nil
-      @string = string
+      @string = string.to_s
       @media_type = "text"
       @subtype_base = @subtype = "plain"
       @subtype_format = nil

lib/cloud_events/errors.rb

@@ -8,28 +8,54 @@ class CloudEventsError < ::StandardError
   end
 
   ##
-  # An error signaling that a protocol handler does not believe that a piece of
-  # data is intended to be a CloudEvent.
+  # 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 NotCloudEventError < ::StandardError
+  class NotCloudEventError < CloudEventsError
   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, 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 HttpContentError < CloudEventsError
+  class UnsupportedFormatError < 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 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.
+  # @private
+  #
+  HttpContentError = UnsupportedFormatError
 end

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"
 

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

lib/cloud_events/http_binding.rb

@@ -129,6 +129,9 @@ def register_formatter_methods formatter,
     # the request.
     #
     # @param env [Hash] The Rack environment.
+    # @param allow_opaque [boolean] If true, returns opaque event objects if
+    #     the input is not in a recognized format. If false, raises
+    #     {CloudEvents::UnsupportedFormatError} in that case. Default is false.
     # @param format_args [keywords] Extra args to pass to the formatter.
     # @return [CloudEvents::Event] if the request includes a single structured
     #     or binary event.
@@ -137,38 +140,76 @@ def register_formatter_methods formatter,
     # @raise [CloudEvents::CloudEventsError] if an event could not be decoded
     #     from the request.
     #
-    def decode_rack_env env, **format_args
+    def decode_rack_env env, allow_opaque: false, **format_args
       content_type_header = env["CONTENT_TYPE"]
       content_type = ContentType.new content_type_header if content_type_header
       if content_type&.media_type == "application"
         case content_type.subtype_base
         when "cloudevents"
           content = read_with_charset env["rack.input"], content_type.charset
-          return decode_structured_content content, content_type, **format_args
+          return decode_structured_content content, content_type, allow_opaque, **format_args
         when "cloudevents-batch"
           content = read_with_charset env["rack.input"], content_type.charset
-          return decode_batched_content content, content_type, **format_args
+          return decode_batched_content content, content_type, allow_opaque, **format_args
         end
       end
       decode_binary_content env, content_type
     end
 
     ##
-    # Encode a single event in the given format.
+    # Encode an event or batch of events into HTTP headers and body.
+    #
+    # You may provide an event, an array of events, or an opaque event. You may
+    # also specify what content mode and format to use.
     #
     # The result is a two-element array where the first element is a headers
     # list (as defined in the Rack specification) and the second is a string
-    # containing the HTTP body content. The headers list will contain only
-    # a `Content-Type` header.
+    # containing the HTTP body content. When using structured content mode, the
+    # headers list will contain only a `Content-Type` header and the body will
+    # contain the serialized event. When using binary mode, the header list
+    # will contain the serialized event attributes and the body will contain
+    # the serialized event data.
+    #
+    # @param event [CloudEvents::Event,Array<CloudEvents::Event>,CloudEvents::Event::Opaque]
+    #     The event, batch, or opaque event.
+    # @param structured_format [boolean,String] If given, the data will be
+    #     encoded in structured content mode. You can pass a string to select
+    #     a format name, or pass `true` to use the default format. If set to
+    #     `false` (the default), the data will be encoded in binary mode.
+    # @param format_args [keywords] Extra args to pass to the formatter.
+    # @return [Array(headers,String)]
+    #
+    def encode_event event, structured_format: false, **format_args
+      if event.is_a? Event::Opaque
+        [{ "Content-Type" => event.content_type.to_s }, event.content]
+      elsif !structured_format
+        encode_binary_content event, **format_args
+      elsif event.is_a? ::Array
+        structured_format = default_batched_encoder if structured_format == true
+        raise ArgumentError, "Format name not specified, and no default is set" unless structured_format
+        encode_batched_content event, structured_format, **format_args
+      elsif event.is_a? Event
+        structured_format = default_structured_encoder if structured_format == true
+        raise ArgumentError, "Format name not specified, and no default is set" unless structured_format
+        encode_structured_content event, structured_format, **format_args
+      else
+        raise ArgumentError, "Unknown event type: #{event.class}"
+      end
+    end
+
+    ##
+    # Encode a single event in structured content mode in the given format.
+    #
+    # @deprecated Will be removed in vresion 1.0. Use encode_event instead.
+    #
+    # @private
     #
     # @param event [CloudEvents::Event] The event.
-    # @param format [String] The format name. Optional.
+    # @param format [String] The format name.
     # @param format_args [keywords] Extra args to pass to the formatter.
     # @return [Array(headers,String)]
     #
-    def encode_structured_content event, format = nil, **format_args
-      format ||= default_structured_encoder
-      raise ArgumentError, "Format name not specified, and no default is set" unless format
+    def encode_structured_content event, format, **format_args
       Array(@event_encoders[format]).reverse_each do |handler|
         result = handler.encode_event event, **format_args
         return [{ "Content-Type" => result[1].to_s }, result[0]] if result
@@ -177,21 +218,18 @@ def encode_structured_content event, format = nil, **format_args
     end
 
     ##
-    # Encode a batch of events to content data in the given format.
+    # Encode a batch of events in structured content mode in the given format.
     #
-    # The result is a two-element array where the first element is a headers
-    # list (as defined in the Rack specification) and the second is a string
-    # containing the HTTP body content. The headers list will contain only
-    # a `Content-Type` header.
+    # @deprecated Will be removed in vresion 1.0. Use encode_event instead.
+    #
+    # @private
     #
     # @param events [Array<CloudEvents::Event>] The batch of events.
-    # @param format [String] The format name. Optional.
+    # @param format [String] The format name.
     # @param format_args [keywords] Extra args to pass to the formatter.
     # @return [Array(headers,String)]
     #
-    def encode_batched_content events, format = nil, **format_args
-      format ||= default_batched_encoder
-      raise ArgumentError, "Format name not specified, and no default is set" unless format
+    def encode_batched_content events, format, **format_args
       Array(@batch_encoders[format]).reverse_each do |handler|
         result = handler.encode_batch events, **format_args
         return [{ "Content-Type" => result[1].to_s }, result[0]] if result
@@ -200,16 +238,17 @@ def encode_batched_content events, format = nil, **format_args
     end
 
     ##
-    # Encode an event to content and headers, in binary content mode.
+    # Encode an event in binary content mode.
     #
-    # The result is a two-element array where the first element is a headers
-    # list (as defined in the Rack specification) and the second is a string
-    # containing the HTTP body content.
+    # @deprecated Will be removed in vresion 1.0. Use encode_event instead.
+    #
+    # @private
     #
     # @param event [CloudEvents::Event] The event.
+    # @param format_args [keywords] Extra args to pass to the formatter.
     # @return [Array(headers,String)]
     #
-    def encode_binary_content event
+    def encode_binary_content event, **format_args
       headers = {}
       body = event.data
       content_type = event.data_content_type
@@ -218,7 +257,7 @@ def encode_binary_content event
           headers["CE-#{key}"] = percent_encode value
         end
       end
-      body, content_type = encode_data body, content_type
+      body, content_type = encode_data body, content_type, **format_args
       headers["Content-Type"] = content_type.to_s if content_type
       [headers, body]
     end
@@ -278,24 +317,26 @@ def add_named_formatter collection, formatter, name
     # Decode a single event from the given request body and content type in
     # structured mode.
     #
-    def decode_structured_content input, content_type, **format_args
+    def decode_structured_content input, content_type, allow_opaque, **format_args
       @event_decoders.reverse_each do |decoder|
         event = decoder.decode_event input, content_type, **format_args
         return event if event
       end
-      raise HttpContentError, "Unknown cloudevents content type: #{content_type}"
+      return Event::Opaque.new input, content_type, batch: false if allow_opaque
+      raise UnsupportedFormatError, "Unknown cloudevents content type: #{content_type}"
     end
 
     ##
     # Decode a batch of events from the given request body and content type in
     # batched structured mode.
     #
-    def decode_batched_content input, content_type, **format_args
+    def decode_batched_content input, content_type, allow_opaque, **format_args
       @batch_decoders.reverse_each do |decoder|
         events = decoder.decode_batch input, content_type, **format_args
         return events if events
       end
-      raise HttpContentError, "Unknown cloudevents content type: #{content_type}"
+      return Event::Opaque.new input, content_type, batch: true if allow_opaque
+      raise UnsupportedFormatError, "Unknown cloudevents content type: #{content_type}"
     end
 
     ##

lib/cloud_events/json_format.rb

@@ -29,6 +29,8 @@ def decode_event input, content_type, **_other_kwargs
       return nil unless content_type&.subtype_format == "json"
       structure = ::JSON.parse input
       decode_hash_structure structure
+    rescue ::JSON::JSONError
+      raise CloudEvents::FormatSyntaxError, "JSON syntax error"
     end
 
     ##
@@ -67,6 +69,8 @@ def decode_batch input, content_type, **_other_kwargs
       structure_array.map do |structure|
         decode_hash_structure structure
       end
+    rescue ::JSON::JSONError
+      raise CloudEvents::FormatSyntaxError, "JSON syntax error"
     end
 
     ##
@@ -104,6 +108,8 @@ def encode_batch events, sort: false, **_other_kwargs
     def decode_data data, content_type, **_other_kwargs
       return nil unless content_type&.subtype_base == "json" || content_type&.subtype_format == "json"
       [::JSON.parse(data), content_type]
+    rescue ::JSON::JSONError
+      raise CloudEvents::FormatSyntaxError, "JSON syntax error"
     end
 
     ##
@@ -193,7 +199,7 @@ def charset_of str
     def decode_hash_structure_v0 structure
       data = structure["data"]
       if data.is_a? ::String
-        content_type = ContentType.new structure["datacontenttype"] rescue nil
+        content_type = ContentType.new structure["datacontenttype"]
         if content_type&.subtype_base == "json" || content_type&.subtype_format == "json"
           structure = structure.dup
           structure["data"] = ::JSON.parse data rescue data