cloud_events 0.3.1 → 0.7.0

data/lib/cloud_events/json_format.rb

@@ -12,56 +12,159 @@ module CloudEvents
   # https://github.com/cloudevents/spec/blob/v1.0/json-format.md.
   #
   class JsonFormat
+    # @private
+    UNSPECIFIED = ::Object.new.freeze
+
     ##
-    # Decode an event from the given input JSON string.
+    # Decode an event or batch from the given input JSON string.
+    # See {CloudEvents::Format#decode_event} for a general description.
     #
-    # @param json [String] A JSON-formatted string
-    # @return [CloudEvents::Event]
+    # Expects `:content` and `:content_type` arguments, and will decline the
+    # request unless both are provided.
+    #
+    # If decoding succeeded, returns a hash with _one of_ the following keys:
+    #
+    # * `:event` ({CloudEvents::Event}) A single event decoded from the input.
+    # * `:event_batch` (Array of {CloudEvents::Event}) A batch of events
+    #   decoded from the input.
     #
-    def decode json, **_other_kwargs
-      structure = ::JSON.parse json
-      decode_hash_structure structure
+    # @param content [String] Serialized content to decode.
+    # @param content_type [CloudEvents::ContentType] The input content type.
+    # @param data_decoder [#decode_data] Optional data field decoder, used for
+    #     non-JSON content types.
+    # @return [Hash] if accepting the request.
+    # @return [nil] if declining the request.
+    # @raise [CloudEvents::FormatSyntaxError] if the JSON could not be parsed
+    # @raise [CloudEvents::SpecVersionError] if an unsupported specversion is
+    #     found.
+    #
+    def decode_event content: nil, content_type: nil, data_decoder: nil, **_other_kwargs
+      return nil unless content && content_type&.media_type == "application" && content_type&.subtype_format == "json"
+      case content_type.subtype_base
+      when "cloudevents"
+        event = decode_hash_structure ::JSON.parse(content), charset: charset_of(content), data_decoder: data_decoder
+        { event: event }
+      when "cloudevents-batch"
+        charset = charset_of content
+        batch = Array(::JSON.parse(content)).map do |structure|
+          decode_hash_structure structure, charset: charset, data_decoder: data_decoder
+        end
+        { event_batch: batch }
+      end
+    rescue ::JSON::JSONError
+      raise FormatSyntaxError, "JSON syntax error"
     end
 
     ##
-    # Encode an event to a JSON string.
+    # Encode an event or batch to a JSON string. This formatter should be able
+    # to handle any event.
+    # See {CloudEvents::Format#decode_event} for a general description.
     #
-    # @param event [CloudEvents::Event] An input event.
+    # Expects _either_ the `:event` _or_ the `:event_batch` argument, but not
+    # both, and will decline the request unless exactly one is provided.
+    #
+    # If encoding succeeded, returns a hash with the following keys:
+    #
+    # * `:content` (String) The serialized form of the event or batch.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type for the
+    #   output.
+    #
+    # @param event [CloudEvents::Event] An event to encode.
+    # @param event_batch [Array<CloudEvents::Event>] An event batch to encode.
+    # @param data_encoder [#encode_data] Optional data field encoder, used for
+    #     non-JSON content types.
     # @param sort [boolean] Whether to sort keys of the JSON output.
-    # @return [String] The JSON representation.
+    # @return [Hash] if accepting the request.
+    # @return [nil] if declining the request.
+    # @raise [CloudEvents::FormatSyntaxError] if the JSON could not be parsed
     #
-    def encode event, sort: false, **_other_kwargs
-      structure = encode_hash_structure event
-      structure = sort_keys structure if sort
-      ::JSON.dump structure
+    def encode_event event: nil, event_batch: nil, data_encoder: nil, sort: false, **_other_kwargs
+      if event && !event_batch
+        structure = encode_hash_structure event, data_encoder: data_encoder
+        structure = sort_keys structure if sort
+        subtype = "cloudevents"
+      elsif event_batch && !event
+        structure = event_batch.map do |elem|
+          structure_elem = encode_hash_structure elem, data_encoder: data_encoder
+          sort ? sort_keys(structure_elem) : structure_elem
+        end
+        subtype = "cloudevents-batch"
+      else
+        return nil
+      end
+      content = ::JSON.dump structure
+      content_type = ContentType.new "application/#{subtype}+json; charset=#{charset_of content}"
+      { content: content, content_type: content_type }
+    rescue ::JSON::JSONError
+      raise FormatSyntaxError, "JSON syntax error"
     end
 
     ##
-    # Decode a batch of events from the given input string.
+    # Decode an event data object from a JSON formatted string.
+    # See {CloudEvents::Format#decode_data} for a general description.
+    #
+    # Expects `:spec_version`, `:content` and `:content_type` arguments, and
+    # will decline the request unless all three are provided.
+    #
+    # If decoding succeeded, returns a hash with the following keys:
+    #
+    # * `:data` (Object) The payload object to set as the `data` attribute.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type to be set
+    #   as the `datacontenttype` attribute.
     #
-    # @param json [String] A JSON-formatted string
-    # @return [Array<CloudEvents::Event>]
+    # @param content [String] Serialized content to decode.
+    # @param content_type [CloudEvents::ContentType] The input content type.
+    # @return [Hash] if accepting the request.
+    # @return [nil] if declining the request.
+    # @raise [CloudEvents::FormatSyntaxError] if the JSON could not be parsed.
+    # @raise [CloudEvents::SpecVersionError] if an unsupported specversion is
+    #     found.
     #
-    def decode_batch json, **_other_kwargs
-      structure_array = Array(::JSON.parse(json))
-      structure_array.map do |structure|
-        decode_hash_structure structure
+    def decode_data spec_version: nil, content: nil, content_type: nil, **_other_kwargs
+      return nil unless spec_version
+      return nil unless content
+      return nil unless json_content_type? content_type
+      unless spec_version =~ /^0\.3|1(\.|$)/
+        raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
+      data = ::JSON.parse content
+      { data: data, content_type: content_type }
+    rescue ::JSON::JSONError
+      raise FormatSyntaxError, "JSON syntax error"
     end
 
     ##
-    # Encode a batch of event to a JSON string.
+    # Encode an event data object to a JSON formatted string.
+    # See {CloudEvents::Format#encode_data} for a general description.
+    #
+    # Expects `:spec_version`, `:data` and `:content_type` arguments, and will
+    # decline the request unless all three are provided.
+    # The `:data` object can be any Ruby object that can be interpreted as
+    # JSON. Most Ruby objects will work, but normally it will be a JSON value
+    # type comprising hashes, arrays, strings, numbers, booleans, or nil.
+    #
+    # If decoding succeeded, returns a hash with the following keys:
     #
-    # @param events [Array<CloudEvents::Event>] An array of input events.
+    # * `:content` (String) The serialized form of the data.
+    # * `:content_type` ({CloudEvents::ContentType}) The content type for the
+    #   output.
+    #
+    # @param data [Object] A data object to encode.
+    # @param content_type [CloudEvents::ContentType] The input content type
     # @param sort [boolean] Whether to sort keys of the JSON output.
-    # @return [String] The JSON representation.
+    # @return [Hash] if accepting the request.
+    # @return [nil] if declining the request.
     #
-    def encode_batch events, sort: false, **_other_kwargs
-      structure_array = Array(events).map do |event|
-        structure = encode_hash_structure event
-        sort ? sort_keys(structure) : structure
+    def encode_data spec_version: nil, data: UNSPECIFIED, content_type: nil, sort: false, **_other_kwargs
+      return nil unless spec_version
+      return nil if data == UNSPECIFIED
+      return nil unless json_content_type? content_type
+      unless spec_version =~ /^0\.3|1(\.|$)/
+        raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
-      ::JSON.dump structure_array
+      data = sort_keys data if sort
+      content = ::JSON.dump data
+      { content: content, content_type: content_type }
     end
 
     ##
@@ -69,15 +172,19 @@ module CloudEvents
     # conforming to the JSON envelope.
     #
     # @param structure [Hash] An input hash.
+    # @param charset [String] The charset of the original encoded JSON document
+    #     if known. Used to provide default content types.
+    # @param data_decoder [#decode_data] Optional data field decoder, used for
+    #     non-JSON content types.
     # @return [CloudEvents::Event]
     #
-    def decode_hash_structure structure
+    def decode_hash_structure structure, charset: nil, data_decoder: nil
       spec_version = structure["specversion"].to_s
       case spec_version
       when "0.3"
-        decode_hash_structure_v0 structure
+        decode_hash_structure_v0 structure, charset
       when /^1(\.|$)/
-        decode_hash_structure_v1 structure
+        decode_hash_structure_v1 structure, charset, spec_version, data_decoder
       else
         raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
       end
@@ -88,70 +195,134 @@ module CloudEvents
     # conforming to the JSON envelope.
     #
     # @param event [CloudEvents::Event] An input event.
+    # @param data_encoder [#encode_data] Optional data field encoder, used for
+    #     non-JSON content types.
     # @return [String] The hash structure.
     #
-    def encode_hash_structure event
+    def encode_hash_structure event, data_encoder: nil
       case event
       when Event::V0
         encode_hash_structure_v0 event
       when Event::V1
-        encode_hash_structure_v1 event
+        encode_hash_structure_v1 event, data_encoder
       else
-        raise SpecVersionError, "Unrecognized specversion: #{event.spec_version}"
+        raise SpecVersionError, "Unrecognized event type: #{event.class}"
       end
     end
 
     private
 
-    def sort_keys hash
+    def json_content_type? content_type
+      content_type&.subtype_base == "json" || content_type&.subtype_format == "json"
+    end
+
+    def sort_keys obj
+      return obj unless obj.is_a? ::Hash
       result = {}
-      hash.keys.sort.each do |key|
-        result[key] = hash[key]
+      obj.keys.sort.each do |key|
+        result[key] = sort_keys obj[key]
       end
       result
     end
 
-    def decode_hash_structure_v0 structure
-      data = structure["data"]
-      content_type = structure["datacontenttype"]
-      if data.is_a?(::String) && content_type.is_a?(::String)
-        content_type = ContentType.new content_type
-        if content_type.subtype == "json" || content_type.subtype_format == "json"
-          structure = structure.dup
-          structure["data"] = ::JSON.parse data rescue data
-          structure["datacontenttype"] = content_type
-        end
+    def charset_of str
+      encoding = str.encoding
+      if encoding == ::Encoding::ASCII_8BIT
+        "binary"
+      else
+        encoding.name.downcase
+      end
+    end
+
+    def decode_hash_structure_v0 structure, charset
+      unless structure.key? "datacontenttype"
+        structure = structure.dup
+        content_type = "application/json"
+        content_type = "#{content_type}; charset=#{charset}" if charset
+        structure["datacontenttype"] = content_type
       end
       Event::V0.new attributes: structure
     end
 
-    def decode_hash_structure_v1 structure
+    def decode_hash_structure_v1 structure, charset, spec_version, data_decoder
+      unless structure.key?("data") || structure.key?("data_base64")
+        return Event::V1.new set_attributes: structure
+      end
+      structure = structure.dup
+      content, content_type = retrieve_content_from_data_fields structure, charset
+      populate_data_fields_from_content structure, content, content_type, spec_version, data_decoder
+      Event::V1.new set_attributes: structure
+    end
+
+    def retrieve_content_from_data_fields structure, charset
       if structure.key? "data_base64"
-        structure = structure.dup
-        structure["data"] = ::Base64.decode64 structure.delete "data_base64"
+        content = ::Base64.decode64 structure.delete "data_base64"
+        content_type = structure["datacontenttype"] || "application/octet-stream"
+      else
+        content = structure["data"]
+        content_type = structure["datacontenttype"]
+        content_type ||= charset ? "application/json; charset=#{charset}" : "application/json"
       end
-      Event::V1.new attributes: structure
+      [content, ContentType.new(content_type)]
+    end
+
+    def populate_data_fields_from_content structure, content, content_type, spec_version, data_decoder
+      if json_content_type? content_type
+        structure["data_encoded"] = ::JSON.dump content
+        structure["data"] = content
+      else
+        structure["data_encoded"] = content = content.to_s
+        result = data_decoder&.decode_data spec_version: spec_version, content: content, content_type: content_type
+        if result
+          structure["data"] = result[:data]
+          content_type = result[:content_type]
+        else
+          structure.delete "data"
+        end
+      end
+      structure["datacontenttype"] = content_type
     end
 
     def encode_hash_structure_v0 event
       structure = event.to_h
-      data = event.data
+      structure["datacontenttype"] ||= "application/json"
+      structure
+    end
+
+    def encode_hash_structure_v1 event, data_encoder
+      structure = event.to_h
+      return structure unless structure.key?("data") || structure.key?("data_encoded")
       content_type = event.data_content_type
-      if data.is_a?(::String) && !content_type.nil? &&
-         (content_type.subtype == "json" || content_type.subtype_format == "json")
-        structure["data"] = ::JSON.parse data rescue data
+      if content_type.nil? || json_content_type?(content_type)
+        encode_data_fields_for_json_content structure, event
+      else
+        encode_data_fields_for_other_content structure, event, data_encoder
       end
       structure
     end
 
-    def encode_hash_structure_v1 event
-      structure = event.to_h
-      data = structure["data"]
-      if data.is_a?(::String) && data.encoding == ::Encoding::ASCII_8BIT
+    def encode_data_fields_for_json_content structure, event
+      structure["data"] = ::JSON.parse event.data unless event.data_decoded?
+      structure.delete "data_encoded"
+      structure["datacontenttype"] ||= "application/json"
+    end
+
+    def encode_data_fields_for_other_content structure, event, data_encoder
+      data_encoded = structure.delete "data_encoded"
+      unless data_encoded
+        result = data_encoder&.encode_data spec_version: event.spec_version,
+                                           data: event.data,
+                                           content_type: event.data_content_type
+        raise UnsupportedFormatError, "Unable to encode data of media type #{event.data_content_type}" unless result
+        data_encoded = result[:content]
+        structure["datacontenttype"] = result[:content_type].to_s
+      end
+      if data_encoded.encoding == ::Encoding::ASCII_8BIT
+        structure["data_base64"] = ::Base64.encode64 data_encoded
         structure.delete "data"
-        structure["data_base64"] = ::Base64.encode64 data
+      else
+        structure["data"] = data_encoded
       end
-      structure
     end
   end
 end

data/lib/cloud_events/text_format.rb

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

data/lib/cloud_events/version.rb

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

data/lib/cloud_events.rb

@@ -3,8 +3,10 @@
 require "cloud_events/content_type"
 require "cloud_events/errors"
 require "cloud_events/event"
+require "cloud_events/format"
 require "cloud_events/http_binding"
 require "cloud_events/json_format"
+require "cloud_events/text_format"
 
 ##
 # CloudEvents implementation.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cloud_events
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-25 00:00:00.000000000 Z
+date: 2022-01-14 00:00:00.000000000 Z
 dependencies: []
 description: The official Ruby implementation of the CloudEvents Specification. Provides
   data types for events, and HTTP/JSON bindings for marshalling and unmarshalling
@@ -28,20 +28,23 @@ files:
 - lib/cloud_events/errors.rb
 - lib/cloud_events/event.rb
 - lib/cloud_events/event/field_interpreter.rb
+- lib/cloud_events/event/opaque.rb
 - lib/cloud_events/event/utils.rb
 - lib/cloud_events/event/v0.rb
 - lib/cloud_events/event/v1.rb
+- lib/cloud_events/format.rb
 - lib/cloud_events/http_binding.rb
 - lib/cloud_events/json_format.rb
+- lib/cloud_events/text_format.rb
 - lib/cloud_events/version.rb
 homepage: https://github.com/cloudevents/sdk-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://cloudevents.github.io/sdk-ruby/v0.3.1/file.CHANGELOG.html
+  changelog_uri: https://cloudevents.github.io/sdk-ruby/v0.7.0/file.CHANGELOG.html
   source_code_uri: https://github.com/cloudevents/sdk-ruby
   bug_tracker_uri: https://github.com/cloudevents/sdk-ruby/issues
-  documentation_uri: https://cloudevents.github.io/sdk-ruby/v0.3.1
+  documentation_uri: https://cloudevents.github.io/sdk-ruby/v0.7.0
 post_install_message: 
 rdoc_options: []
 require_paths: