cloud_events 0.1.2 → 0.5.1

data/lib/cloud_events/event/v1.rb

@@ -3,6 +3,9 @@
 require "date"
 require "uri"
 
+require "cloud_events/event/field_interpreter"
+require "cloud_events/event/utils"
+
 module CloudEvents
   module Event
     ##
@@ -16,9 +19,10 @@ module CloudEvents
     # their own accessor methods that may return typed objects (such as
     # `DateTime` for the `time` attribute).
     #
-    # This object is immutable. The data and attribute values can be
-    # retrieved but not modified. To obtain an event with modifications, use
-    # the {#with} method to create a copy with the desired changes.
+    # 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
+    # with modifications, use the {#with} method to create a copy with the
+    # desired changes.
     #
     # See https://github.com/cloudevents/spec/blob/v1.0/spec.md for
     # descriptions of the standard attributes.
@@ -42,7 +46,7 @@ module CloudEvents
       #     field.
       #  *  **:type** [`String`] - _required_ - The event `type` field.
       #  *  **:data** [`Object`] - _optional_ - The data associated with the
-      #     event (i.e. the `data` field.)
+      #     event (i.e. the `data` field).
       #  *  **: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.)
@@ -56,6 +60,11 @@ module CloudEvents
       # They are not available as separate methods, but can be accessed via
       # the {Event::V1#[]} operator.
       #
+      # Note that attribute objects passed in may get deep-frozen if they are
+      # used in the final event object. This is particularly important for the
+      # `: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 args [keywords] The data and attributes, as keyword arguments.
       #
@@ -65,12 +74,13 @@ module CloudEvents
         @id = interpreter.string ["id"], required: true
         @source = interpreter.uri ["source"], required: true
         @type = interpreter.string ["type"], required: true
-        @data = interpreter.object ["data"], allow_nil: true
+        @data = interpreter.data_object ["data"]
         @data_content_type = interpreter.content_type ["datacontenttype", "data_content_type"]
         @data_schema = interpreter.uri ["dataschema", "data_schema"]
         @subject = interpreter.string ["subject"]
         @time = interpreter.rfc3339_date_time ["time"]
         @attributes = interpreter.finish_attributes
+        freeze
       end
 
       ##
@@ -101,6 +111,8 @@ module CloudEvents
       #     event["time"]     # => String rfc3339 representation
       #     event.time        # => DateTime object
       #
+      # Results are also always frozen and cannot be modified in place.
+      #
       # @param key [String,Symbol] The attribute name.
       # @return [String,nil]
       #
@@ -109,12 +121,13 @@ module CloudEvents
       end
 
       ##
-      # Return a hash representation of this event.
+      # Return a hash representation of this event. The returned hash is an
+      # unfrozen deep copy. Modifications do not affect the original event.
       #
       # @return [Hash]
       #
       def to_h
-        @attributes.dup
+        Utils.deep_dup @attributes
       end
 
       ##
@@ -201,7 +214,7 @@ module CloudEvents
 
       ## @private
       def hash
-        @hash ||= @attributes.hash
+        @attributes.hash
       end
     end
   end

data/lib/cloud_events/format.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+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
+  # decoding strategies for a particular format (such as JSON). In general,
+  # this includes four operations:
+  #
+  # * Decoding an entire event or batch of events from a input source.
+  #   This is implemented by the {Format#decode_event} method.
+  # * Encoding an entire event or batch of events to an output sink.
+  #   This is implemented by the {Format#encode_event} method.
+  # * Decoding an event payload (i.e. the `data` attribute) Ruby object from a
+  #   serialized representation.
+  #   This is implemented by the {Format#decode_data} method.
+  # * Encoding an event payload (i.e. the `data` attribute) Ruby object to a
+  #   serialized representation.
+  #   This is implemented by the {Format#encode_data} method.
+  #
+  # Each method takes a set of keyword arguments, and returns either a `Hash`
+  # or `nil`. A Hash indicates that the formatter understands the request and
+  # is returning its response. A return value of `nil` means the formatter does
+  # not understand the request and is declining to perform the operation. In
+  # such a case, it is possible that a different formatter should handle it.
+  #
+  # Both the keyword arguments recognized and the returned hash members may
+  # vary from formatter to formatter; similarly, the keyword arguments provided
+  # and the resturned hash members recognized may also vary for different
+  # callers. This interface will define a set of common argument and result key
+  # names, but both callers and formatters must gracefully handle the case of
+  # missing or extra information. For example, if a formatter expects a certain
+  # argument but does not receive it, it can assume the caller does not have
+  # the required information, and it may respond by returning `nil` to decline
+  # the request. Similarly, if a caller expects a response key but does not
+  # receive it, it can assume the formatter does not provide it, and it may
+  # respond by trying a different formatter.
+  #
+  # Additionally, any particular formatter need not implement all methods. For
+  # example, an event formatter would generally implement {Format#decode_event}
+  # and {Format#encode_event}, but might not implement {Format#decode_data} or
+  # {Format#encode_data}.
+  #
+  # Finally, this module itself is present primarily for documentation, and
+  # need not be directly included by formatter implementations.
+  #
+  module Format
+    ##
+    # Decode an event or batch from the given serialized input. This is
+    # typically called by a protocol binding to deserialize event data from an
+    # input stream.
+    #
+    # Common arguments include:
+    #
+    # * `:content` (String) Serialized content to decode. For example, it could
+    #   be from an HTTP request body.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type. For
+    #   example, it could be from the `Content-Type` header of an HTTP request.
+    #
+    # The formatter must first determine whether it is able to interpret the
+    # given input. Typically, this is done by inspecting the `content_type`.
+    # If the formatter determines that it is unable to interpret the input, it
+    # should return `nil`. Otherwise, if the formatter determines it can decode
+    # the input, it should return a `Hash`. Common hash keys include:
+    #
+    # * `:event` ({CloudEvents::Event}) A single event decoded from the input.
+    # * `:event_batch` (Array of {CloudEvents::Event}) A batch of events
+    #   decoded from the input.
+    #
+    # The formatter may also raise a {CloudEvents::CloudEventsError} subclass
+    # if it understood the request but determines that the input source is
+    # malformed.
+    #
+    # @param _kwargs [keywords] Arguments
+    # @return [Hash] if accepting the request and returning a result
+    # @return [nil] if declining the request.
+    #
+    def decode_event **_kwargs
+      nil
+    end
+
+    ##
+    # Encode an event or batch to a string. This is typically called by a
+    # protocol binding to serialize event data to an output stream.
+    #
+    # Common arguments include:
+    #
+    # * `:event` ({CloudEvents::Event}) A single event to encode.
+    # * `:event_batch` (Array of {CloudEvents::Event}) A batch of events to
+    #   encode.
+    #
+    # The formatter must first determine whether it is able to interpret the
+    # given input. Typically, most formatters should be able to handle any
+    # event or event batch, but a specialized formatter that can handle only
+    # certain kinds of events may return `nil` to decline unwanted inputs.
+    # Otherwise, if the formatter determines it can encode the input, it should
+    # return a `Hash`. common hash keys include:
+    #
+    # * `:content` (String) The serialized form of the event. 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`.
+    # * `: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.
+    #
+    # The formatter may also raise a {CloudEvents::CloudEventsError} subclass
+    # if it understood the request but determines that the input source is
+    # malformed.
+    #
+    # @param _kwargs [keywords] Arguments
+    # @return [Hash] if accepting the request and returning a result
+    # @return [nil] if declining the request.
+    #
+    def encode_event **_kwargs
+      nil
+    end
+
+    ##
+    # Decode an event data object from string format. This is typically called
+    # by a protocol binding to deserialize the payload (i.e. `data` attribute)
+    # of an event as part of "binary content mode" decoding.
+    #
+    # Common arguments include:
+    #
+    # * `:spec_version` (String) The `specversion` of the event.
+    # * `:content` (String) Serialized payload to decode. For example, it could
+    #   be from an HTTP request body.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type. For
+    #   example, it could be from the `Content-Type` header of an HTTP request.
+    #
+    # The formatter must first determine whether it is able to interpret the
+    # given input. Typically, this is done by inspecting the `content_type`.
+    # If the formatter determines that it is unable to interpret the input, it
+    # should return `nil`. Otherwise, if the formatter determines it can decode
+    # the input, it should return a `Hash`. Common hash keys include:
+    #
+    # * `:data` (Object) The payload object to be set as the `data` attribute
+    #   in a {CloudEvents::Event} object.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type to be set
+    #   as the `datacontenttype` attribute in a {CloudEvents::Event} object.
+    #   In many cases, this may simply be copied from the `:content_type`
+    #   argument, but a formatter could modify it to provide corrections or
+    #   additional information.
+    #
+    # The formatter may also raise a {CloudEvents::CloudEventsError} subclass
+    # if it understood the request but determines that the input source is
+    # malformed.
+    #
+    # @param _kwargs [keywords] Arguments
+    # @return [Hash] if accepting the request and returning a result
+    # @return [nil] if declining the request.
+    #
+    def decode_data **_kwargs
+      nil
+    end
+
+    ##
+    # Encode an event data object to string format. This is typically called by
+    # a protocol binding to serialize the payload (i.e. `data` attribute and
+    # corresponding `datacontenttype` attribute) of an event as part of "binary
+    # content mode" encoding.
+    #
+    # Common arguments include:
+    #
+    # * `:spec_version` (String) The `specversion` of the event.
+    # * `:data` (Object) The payload object from an event's `data` attribute.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type from an
+    #   event's `datacontenttype` attribute.
+    #
+    # The formatter must first determine whether it is able to interpret the
+    # given input. Typically, this is done by inspecting the `content_type`.
+    # If the formatter determines that it is unable to interpret the input, it
+    # should return `nil`. Otherwise, if the formatter determines it can decode
+    # the input, it should return a `Hash`. Common hash keys include:
+    #
+    # * `: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`.
+    # * `: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.
+    #
+    # The formatter may also raise a {CloudEvents::CloudEventsError} subclass
+    # if it understood the request but determines that the input source is
+    # malformed.
+    #
+    # @param _kwargs [keywords] Arguments
+    # @return [Hash] if accepting the request and returning a result
+    # @return [nil] if declining the request.
+    #
+    def encode_data **_kwargs
+      nil
+    end
+  end
+end

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,234 +38,284 @@ 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.
+    # 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.
     #
-    # A batch formatter must respond to the methods `#encode_batch` and
-    # `#decode_batch`. 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 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"
-          input.set_encoding content_type.charset if content_type.charset
-          return decode_structured_content input.read, content_type.subtype_format, **format_args
-        when "cloudevents-batch"
-          input.set_encoding content_type.charset if content_type.charset
-          return decode_batched_content input.read, 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 = if input
-               input.set_encoding content_type.charset if content_type&.charset
-               input.read
-             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
+    # @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
-        return [{ "Content-Type" => "application/cloudevents+#{format}" }, content] if 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
-        return [{ "Content-Type" => "application/cloudevents-batch+#{format}" }, content] if 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|
-        if key == "data"
-          body = value
-        elsif key == "datacontenttype"
-          headers["Content-Type"] = value
-        else
+        unless ["data", "datacontenttype"].include? key
           headers["CE-#{key}"] = percent_encode value
         end
       end
-      if body.is_a? ::String
-        headers["Content-Type"] ||= if body.encoding == ::Encoding.ASCII_8BIT
-                                      "application/octet-stream"
-                                    else
-                                      "text/plain; charset=#{body.encoding.name.downcase}"
-                                    end
-      elsif body.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.
     #
     def percent_decode str
+      str = str.gsub(/"((?:[^"\\]|\\.)*)"/) { ::Regexp.last_match(1).gsub(/\\(.)/, '\1') }
       decoded_str = str.gsub(/%[0-9a-fA-F]{2}/) { |m| [m[1..-1].to_i(16)].pack "C" }
       decoded_str.force_encoding ::Encoding::UTF_8
     end
@@ -268,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.
@@ -276,7 +335,7 @@ module CloudEvents
       arr = []
       utf_str = str.to_s.encode ::Encoding::UTF_8
       utf_str.each_byte do |byte|
-        if byte >= 33 && byte <= 126 && byte != 37
+        if byte >= 33 && byte <= 126 && byte != 34 && byte != 37
           arr << byte
         else
           hi = byte / 16
@@ -288,5 +347,120 @@ module CloudEvents
       end
       arr.pack "C*"
     end
+
+    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
+          str.force_encoding charset
+        rescue ::ArgumentError
+          # Use binary for now if the charset is unrecognized
+          str.force_encoding ::Encoding::ASCII_8BIT
+        end
+      end
+      str
+    end
+
+    # @private
+    module DefaultDataFormat
+      # @private
+      def self.decode_data content: nil, content_type: nil, **_extra_kwargs
+        { data: content, content_type: content_type }
+      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 }
+      end
+    end
   end
 end