cloud_events 0.4.0 → 0.5.1

data/lib/cloud_events/http_binding.rb

@@ -15,14 +15,21 @@ module CloudEvents
   #
   class HttpBinding
     ##
-    # Returns a default binding, with JSON supported.
+    # The name of the JSON decoder/encoder
+    # @return [String]
+    #
+    JSON_FORMAT = "json"
+
+    ##
+    # Returns a default HTTP binding, including support for JSON format.
+    #
+    # @return [HttpBinding]
     #
     def self.default
       @default ||= begin
         http_binding = new
-        json_format = JsonFormat.new
-        http_binding.register_structured_formatter "json", json_format
-        http_binding.register_batched_formatter "json", json_format
+        http_binding.register_formatter JsonFormat.new, JSON_FORMAT
+        http_binding.default_encoder_name = JSON_FORMAT
         http_binding
       end
     end
@@ -31,230 +38,278 @@ module CloudEvents
     # Create an empty HTTP binding.
     #
     def initialize
-      @structured_formatters = {}
-      @batched_formatters = {}
+      @event_decoders = []
+      @event_encoders = {}
+      @data_decoders = [DefaultDataFormat]
+      @data_encoders = [DefaultDataFormat]
+      @default_encoder_name = nil
     end
 
     ##
-    # Register a formatter for the given type.
+    # Register a formatter for all operations it supports, based on which
+    # methods are implemented by the formatter object. See
+    # {CloudEvents::Format} for a list of possible methods.
     #
-    # A formatter must respond to the methods `#encode` and `#decode`. See
-    # {CloudEvents::JsonFormat} for an example.
-    #
-    # @param type [String] The subtype format that should be handled by
-    #     this formatter.
-    # @param formatter [Object] The formatter object.
+    # @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.
     # @return [self]
     #
-    def register_structured_formatter type, formatter
-      formatters = @structured_formatters[type.to_s.strip.downcase] ||= []
-      formatters << formatter unless formatters.include? formatter
+    def register_formatter formatter, name = nil
+      name = name.to_s.strip.downcase if name
+      decode_event = formatter.respond_to? :decode_event
+      encode_event = 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,
+                                 decode_event: decode_event,
+                                 encode_event: encode_event,
+                                 decode_data: decode_data,
+                                 encode_data: encode_data
       self
     end
 
     ##
-    # Register a batch formatter for the given type.
-    #
-    # A batch formatter must respond to the methods `#encode_batch` and
-    # `#decode_batch`. See {CloudEvents::JsonFormat} for an example.
+    # Registers the given formatter for the given operations. Some arguments
+    # are activated by passing `true`, whereas those that rely on a format name
+    # are activated by passing in a name string.
     #
-    # @param type [String] The subtype format that should be handled by
-    #     this formatter.
-    # @param formatter [Object] The formatter object.
+    # @param formatter [Object] The formatter
+    # @param decode_event [boolean] If true, register the formatter's
+    #     {CloudEvents::Format#decode_event} method.
+    # @param encode_event [String] If set to a string, use the formatter's
+    #     {CloudEvents::Format#encode_event} method when that name is requested.
+    # @param decode_data [boolean] If true, register the formatter's
+    #     {CloudEvents::Format#decode_data} method.
+    # @param encode_data [boolean] If true, register the formatter's
+    #     {CloudEvents::Format#encode_data} method.
     # @return [self]
     #
-    def register_batched_formatter type, formatter
-      formatters = @batched_formatters[type.to_s.strip.downcase] ||= []
-      formatters << formatter unless formatters.include? formatter
+    def register_formatter_methods formatter,
+                                   decode_event: false,
+                                   encode_event: nil,
+                                   decode_data: false,
+                                   encode_data: false
+      @event_decoders << formatter if decode_event
+      if encode_event
+        formatters = @event_encoders[encode_event] ||= []
+        formatters << formatter unless formatters.include? formatter
+      end
+      @data_decoders << formatter if decode_data
+      @data_encoders << 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
+
+    ##
+    # Analyze a Rack environment hash and determine whether it is _probably_
+    # a CloudEvent. This is done by examining headers only, and does not read
+    # or parse the request body. The result is a best guess: false negatives or
+    # false positives are possible for edge cases, but the logic should
+    # generally detect canonically-formatted events.
+    #
+    # @param env [Hash] The Rack environment.
+    # @return [boolean] Whether the request is likely a CloudEvent.
+    #
+    def probable_event? env
+      return true if env["HTTP_CE_SPECVERSION"]
+      content_type = ContentType.new env["CONTENT_TYPE"].to_s
+      content_type.media_type == "application" &&
+        ["cloudevents", "cloudevents-batch"].include?(content_type.subtype_base)
+    end
+
     ##
     # Decode an event from the given Rack environment hash. Following the
     # CloudEvents spec, this chooses a handler based on the Content-Type of
     # the request.
     #
+    # Note that this method will read the body (i.e. `rack.input`) stream.
+    # If you need to access the body after calling this method, you will need
+    # to rewind the stream. To determine whether the request is a CloudEvent
+    # without reading the body, use {#probable_event?}.
+    #
     # @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.
     # @return [Array<CloudEvents::Event>] if the request includes a batch of
     #     structured events.
-    # @return [nil] if the request was not recognized as a CloudEvent.
+    # @raise [CloudEvents::CloudEventsError] if an event could not be decoded
+    #     from the request.
     #
-    def decode_rack_env env, **format_args
-      content_type_header = env["CONTENT_TYPE"]
-      content_type = ContentType.new content_type_header if content_type_header
-      input = env["rack.input"]
-      if input && content_type&.media_type == "application"
-        case content_type.subtype_base
-        when "cloudevents"
-          content = read_with_charset input, content_type.charset
-          return decode_structured_content content, content_type.subtype_format, **format_args
-        when "cloudevents-batch"
-          content = read_with_charset input, content_type.charset
-          return decode_batched_content content, content_type.subtype_format, **format_args
-        end
+    def decode_event env, allow_opaque: false, **format_args
+      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) ||
+               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"
+        raise NotCloudEventError, "Content-Type is #{content_type_string}, and CE-SpecVersion is not present"
       end
-      decode_binary_content env, content_type
+      result
     end
 
     ##
-    # Decode a single event from the given content data. This should be
-    # passed the request body, if the Content-Type is of the form
-    # `application/cloudevents+format`.
+    # Encode an event or batch of events into HTTP headers and body.
     #
-    # @param input [String] The string content.
-    # @param format [String] The format code (e.g. "json").
-    # @param format_args [keywords] Extra args to pass to the formatter.
-    # @return [CloudEvents::Event]
+    # You may provide an event, an array of events, or an opaque event. You may
+    # also specify what content mode and format to use.
     #
-    def decode_structured_content input, format, **format_args
-      handlers = @structured_formatters[format] || []
-      handlers.reverse_each do |handler|
-        event = handler.decode input, **format_args
-        return event if event
-      end
-      raise HttpContentError, "Unknown cloudevents format: #{format.inspect}"
-    end
-
-    ##
-    # Decode a batch of events from the given content data. This should be
-    # passed the request body, if the Content-Type is of the form
-    # `application/cloudevents-batch+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. 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 input [String] The string content.
-    # @param format [String] The format code (e.g. "json").
+    # @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<CloudEvents::Event>]
+    # @return [Array(headers,String)]
     #
-    def decode_batched_content input, format, **format_args
-      handlers = @batched_formatters[format] || []
-      handlers.reverse_each do |handler|
-        events = handler.decode_batch input, **format_args
-        return events if events
+    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
+        if event.is_a? ::Array
+          raise ::ArgumentError, "Encoding a batch requires structured_format"
+        end
+        encode_binary_content event, legacy_data_encode: false, **format_args
+      else
+        structured_format = default_encoder_name if structured_format == true
+        raise ::ArgumentError, "Format name not specified, and no default is set" unless structured_format
+        case event
+        when ::Array
+          encode_batched_content event, structured_format, **format_args
+        when Event
+          encode_structured_content event, structured_format, **format_args
+        else
+          raise ::ArgumentError, "Unknown event type: #{event.class}"
+        end
       end
-      raise HttpContentError, "Unknown cloudevents batch format: #{format.inspect}"
     end
 
     ##
-    # Decode an event from the given Rack environment in binary content mode.
+    # Decode an event from the given Rack environment hash. Following the
+    # CloudEvents spec, this chooses a handler based on the Content-Type of
+    # the request.
     #
-    # @param env [Hash] Rack environment hash.
-    # @param content_type [CloudEvents::ContentType] the content type from the
-    #     Rack environment.
-    # @return [CloudEvents::Event] if a CloudEvent could be decoded from the
-    #     Rack environment.
-    # @return [nil] if the Rack environment does not indicate a CloudEvent
+    # @deprecated Will be removed in version 1.0. Use {#decode_event} instead.
     #
-    def decode_binary_content env, content_type
-      spec_version = env["HTTP_CE_SPECVERSION"]
-      return nil if spec_version.nil?
-      raise SpecVersionError, "Unrecognized specversion: #{spec_version}" unless spec_version == "1.0"
-      input = env["rack.input"]
-      data = read_with_charset input, content_type&.charset if input
-      attributes = { "spec_version" => spec_version, "data" => data }
-      attributes["data_content_type"] = content_type if content_type
-      omit_names = ["specversion", "spec_version", "data", "datacontenttype", "data_content_type"]
-      env.each do |key, value|
-        match = /^HTTP_CE_(\w+)$/.match key
-        next unless match
-        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
+    # @param env [Hash] The Rack environment.
+    # @param format_args [keywords] Extra args to pass to the formatter.
+    # @return [CloudEvents::Event] if the request includes a single structured
+    #     or binary event.
+    # @return [Array<CloudEvents::Event>] if the request includes a batch of
+    #     structured events.
+    # @return [nil] if the request does not appear to be a CloudEvent.
+    # @raise [CloudEvents::CloudEventsError] if the request appears to be a
+    #     CloudEvent but decoding failed.
+    #
+    def decode_rack_env env, **format_args
+      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
+      env["rack.input"].rewind rescue nil
+      decode_binary_content(content, content_type, env, legacy_data_decode: true) ||
+        decode_structured_content(content, content_type, false, **format_args)
     end
 
     ##
-    # Encode a single event to content data in the given format.
+    # Encode a single event 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
-    # one header, a `Content-Type` whose value is of the form
-    # `application/cloudevents+format`.
+    # @deprecated Will be removed in version 1.0. Use {#encode_event} instead.
     #
     # @param event [CloudEvents::Event] The event.
-    # @param format [String] The format code (e.g. "json")
+    # @param format_name [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, **format_args
-      handlers = @structured_formatters[format] || []
-      handlers.reverse_each do |handler|
-        content = handler.encode event, **format_args
-        if content
-          content_type = "application/cloudevents+#{format}; charset=#{charset_of content}"
-          return [{ "Content-Type" => content_type }, content]
+    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
-      raise HttpContentError, "Unknown cloudevents format: #{format.inspect}"
+      raise ::ArgumentError, "Unknown format name: #{format_name.inspect}"
     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
-    # one header, a `Content-Type` whose value is of the form
-    # `application/cloudevents-batch+format`.
+    # @deprecated Will be removed in version 1.0. Use {#encode_event} instead.
     #
-    # @param events [Array<CloudEvents::Event>] The batch of events.
-    # @param format [String] The format code (e.g. "json").
+    # @param event_batch [Array<CloudEvents::Event>] The batch of events.
+    # @param format_name [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, **format_args
-      handlers = @batched_formatters[format] || []
-      handlers.reverse_each do |handler|
-        content = handler.encode_batch events, **format_args
-        if content
-          content_type = "application/cloudevents-batch+#{format}; charset=#{charset_of content}"
-          return [{ "Content-Type" => content_type }, content]
+    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
-      raise HttpContentError, "Unknown cloudevents format: #{format.inspect}"
+      raise ::ArgumentError, "Unknown format name: #{format_name.inspect}"
     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 version 1.0. Use {#encode_event} instead.
     #
     # @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, legacy_data_encode: true, **format_args
       headers = {}
-      body = nil
       event.to_h.each do |key, value|
-        case key
-        when "data"
-          body = value
-        when "datacontenttype"
-          headers["Content-Type"] = value
-        else
+        unless ["data", "datacontenttype"].include? key
           headers["CE-#{key}"] = percent_encode value
         end
       end
-      case body
-      when ::String
-        headers["Content-Type"] ||= string_content_type body
-      when nil
-        headers.delete "Content-Type"
+      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
+        else
+          body = ::JSON.dump body
+          content_type ||= "application/json; charset=#{body.encoding.name.downcase}"
+        end
       else
-        body = ::JSON.dump body
-        headers["Content-Type"] ||= "application/json; charset=#{body.encoding.name.downcase}"
+        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
 
     ##
     # Decode a percent-encoded string to a UTF-8 string.
     #
+    # @private
+    #
     # @param str [String] Incoming ascii string from an HTTP header, with one
     #     cycle of percent-encoding.
     # @return [String] Resulting decoded string in UTF-8.
@@ -270,6 +325,8 @@ module CloudEvents
     # non-printing and non-ascii characters to result in an ASCII string
     # suitable for setting as an HTTP header value.
     #
+    # @private
+    #
     # @param str [String] Incoming arbitrary string that can be represented
     #     in UTF-8.
     # @return [String] Resulting encoded string in ASCII.
@@ -293,7 +350,87 @@ module CloudEvents
 
     private
 
+    def add_named_formatter collection, formatter, name
+      return unless name
+      formatters = collection[name] ||= []
+      formatters << formatter unless formatters.include? formatter
+    end
+
+    ##
+    # Decode a single event from the given request body and content type in
+    # 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
+      if content_type&.media_type == "application" &&
+         ["cloudevents", "cloudevents-batch"].include?(content_type.subtype_base)
+        return Event::Opaque.new content, content_type if allow_opaque
+        raise UnsupportedFormatError, "Unknown cloudevents content type: #{content_type}"
+      end
+      nil
+    end
+
+    ##
+    # Decode an event from the given Rack environment in binary content mode.
+    #
+    # 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
+      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
+      else
+        data, content_type = decode_data spec_version, content, content_type
+      end
+      attributes = { "spec_version" => spec_version, "data" => data }
+      attributes["data_content_type"] = content_type if content_type
+      omit_names = ["specversion", "spec_version", "data", "datacontenttype", "data_content_type"]
+      env.each do |key, value|
+        match = /^HTTP_CE_(\w+)$/.match key
+        next unless match
+        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
+      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
+      end
+      raise "Should not get here"
+    end
+
     def read_with_charset io, charset
+      return nil if io.nil?
       str = io.read
       if charset
         begin
@@ -306,20 +443,23 @@ module CloudEvents
       str
     end
 
-    def string_content_type str
-      if str.encoding == ::Encoding::ASCII_8BIT
-        "application/octet-stream"
-      else
-        "text/plain; charset=#{str.encoding.name.downcase}"
+    # @private
+    module DefaultDataFormat
+      # @private
+      def self.decode_data content: nil, content_type: nil, **_extra_kwargs
+        { data: content, content_type: content_type }
       end
-    end
 
-    def charset_of str
-      encoding = str.encoding
-      if encoding == ::Encoding::ASCII_8BIT
-        "binary"
-      else
-        encoding.name.downcase
+      # @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 }
       end
     end
   end