cloud_events 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae042efe6c2ccd066620bf2e4f548d6f0470fff3426e92442e5f403c8e06273a
-  data.tar.gz: f8d1fbbb00faa1d2b72db8c1e9ac016580951884e78cc6129eeec7fb8d844d5a
+  metadata.gz: d44f430fb349c68608ecb791c8e0727c7c6cef018022a4f28c6dcb140b201d48
+  data.tar.gz: d4f1755b09f71fe1817d227666762c642de19172062a7fbdc29ec2a837a7b31e
 SHA512:
-  metadata.gz: 06a156c8448d1c7b59ef683e90ecba1d22dfbe4564574a9355ee110c31f91240137295c437933ed6038fe8e1a9e9e5b19067ef82ee11affd38c6c2f41dac2b50
-  data.tar.gz: 9d8b7c3745261e6addd427b9b4d24b3873014f998f0f0844889315a6ea59ab3c11e44cbc25abfdffdb758357545c8c62eeca4f5d5138e6bd2179d700e1dd60c6
+  metadata.gz: c0f36a2c0cf43efafbda5b94a7392e5c52ff7974df002d0051013a4db1bd809d62721499c2f0c5f1712907f72dbbea6e2280532d1ac275a0aa33e96e4094eb19
+  data.tar.gz: c18abd09d34d4e7f51ac2f327d10ae99ab7541ee2f13afa2df46c67424e40bc2e99521f64341436858c686261cdab315945173940cd467fa55bc49ead4590096

data/CHANGELOG.md

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

data/README.md

@@ -13,7 +13,7 @@ Features:
     JSON Batch Format.
  *  Support for sending and receiving CloudEvents via HTTP Bindings.
  *  Supports the [CloudEvent 0.3](https://github.com/cloudevents/spec/tree/v0.3)
-    and [CloudEvents 1.0](https://github.com/cloudevents/spec/tree/v1.0)
+    and [CloudEvents 1.0](https://github.com/cloudevents/spec/tree/v1.0.1)
     specifications.
  *  Extensible to additional formats and protocol bindings, and future
     specification versions.
@@ -35,7 +35,7 @@ A simple [Sinatra](https://sinatrarb.com) app that receives CloudEvents:
 ```ruby
 # examples/server/Gemfile
 source "https://rubygems.org"
-gem "cloud_events", "~> 0.2"
+gem "cloud_events", "~> 0.5"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -59,7 +59,7 @@ A simple Ruby script that sends a CloudEvent:
 ```ruby
 # examples/client/Gemfile
 source "https://rubygems.org"
-gem "cloud_events", "~> 0.2"
+gem "cloud_events", "~> 0.5"
 ```
 
 ```ruby
@@ -69,14 +69,16 @@ require "net/http"
 require "uri"
 
 data = { message: "Hello, CloudEvents!" }
-event = CloudEvents::Event.create spec_version: "1.0",
-                                  id:           "1234-1234-1234",
-                                  source:       "/mycontext",
-                                  type:         "com.example.someevent",
-                                  data:         data
+event = CloudEvents::Event.create \
+  spec_version:      "1.0",
+  id:                "1234-1234-1234",
+  source:            "/mycontext",
+  type:              "com.example.someevent",
+  data_content_type: "application/json",
+  data:              data
 
 cloud_events_http = CloudEvents::HttpBinding.default
-headers, body = cloud_events_http.encode_binary_content event
+headers, body = cloud_events_http.encode_event event
 Net::HTTP.post URI("http://localhost:4567"), body, headers
 ```
 

data/lib/cloud_events.rb

@@ -3,6 +3,7 @@
 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"
 

data/lib/cloud_events/content_type.rb

@@ -25,7 +25,7 @@ module CloudEvents
     #     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

data/lib/cloud_events/errors.rb

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

data/lib/cloud_events/event.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"
 

data/lib/cloud_events/event/opaque.rb

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

data/lib/cloud_events/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