cloud_events 0.1.0

data/lib/cloud_events.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "cloud_events/content_type"
+require "cloud_events/errors"
+require "cloud_events/event"
+require "cloud_events/http_binding"
+require "cloud_events/json_format"
+
+##
+# CloudEvents implementation.
+#
+# This is a Ruby implementation of the [CloudEvents](https://cloudevents.io)
+# specification. It supports both
+# [CloudEvents 0.3](https://github.com/cloudevents/spec/blob/v0.3/spec.md) and
+# [CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md).
+#
+module CloudEvents
+  # @private
+  SUPPORTED_SPEC_VERSIONS = ["0.3", "1.0"].freeze
+
+  class << self
+    ##
+    # The spec versions supported by this implementation.
+    #
+    # @return [Array<String>]
+    #
+    def supported_spec_versions
+      SUPPORTED_SPEC_VERSIONS
+    end
+  end
+end

data/lib/cloud_events/content_type.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  ##
+  # A parsed content-type header.
+  #
+  # This object represents the information contained in a Content-Type,
+  # obtained by parsing the header according to RFC 2045.
+  #
+  # Case-insensitive fields, such as media_type and subtype, are normalized
+  # to lower case.
+  #
+  # If parsing fails, this class will try to get as much information as it
+  # can, and fill the rest with defaults as recommended in RFC 2045 sec 5.2.
+  # In case of a parsing error, the {#error_message} field will be set.
+  #
+  class ContentType
+    ##
+    # Parse the given header value.
+    #
+    # @param string [String] Content-Type header value in RFC 2045 format
+    #
+    def initialize string
+      @string = string
+      @media_type = "text"
+      @subtype_base = @subtype = "plain"
+      @subtype_format = nil
+      @params = []
+      @charset = "us-ascii"
+      @error_message = nil
+      parse consume_comments string.strip
+      @canonical_string = "#{@media_type}/#{@subtype}" +
+                          @params.map { |k, v| "; #{k}=#{maybe_quote v}" }.join
+    end
+
+    ##
+    # The original header content string.
+    # @return [String]
+    #
+    attr_reader :string
+    alias to_s string
+
+    ##
+    # A "canonical" header content string with spacing and capitalization
+    # normalized.
+    # @return [String]
+    #
+    attr_reader :canonical_string
+
+    ##
+    # The media type.
+    # @return [String]
+    #
+    attr_reader :media_type
+
+    ##
+    # The entire content subtype (which could include an extension delimited
+    # by a plus sign).
+    # @return [String]
+    #
+    attr_reader :subtype
+
+    ##
+    # The portion of the content subtype before any plus sign.
+    # @return [String]
+    #
+    attr_reader :subtype_base
+
+    ##
+    # The portion of the content subtype after any plus sign, or nil if there
+    # is no plus sign in the subtype.
+    # @return [String,nil]
+    #
+    attr_reader :subtype_format
+
+    ##
+    # An array of parameters, each element as a two-element array of the
+    # parameter name and value.
+    # @return [Array<Array(String,String)>]
+    #
+    attr_reader :params
+
+    ##
+    # The charset, defaulting to "us-ascii" if none is explicitly set.
+    # @return [String]
+    #
+    attr_reader :charset
+
+    ##
+    # The error message when parsing, or `nil` if there was no error message.
+    # @return [String,nil]
+    #
+    attr_reader :error_message
+
+    ##
+    # An array of values for the given parameter name
+    # @param key [String]
+    # @return [Array<String>]
+    #
+    def param_values key
+      key = key.downcase
+      @params.inject([]) { |a, (k, v)| key == k ? a << v : a }
+    end
+
+    ## @private
+    def == other
+      other.is_a?(ContentType) && canonical_string == other.canonical_string
+    end
+    alias eql? ==
+
+    ## @private
+    def hash
+      canonical_string.hash
+    end
+
+    ## @private
+    class ParseError < ::StandardError
+    end
+
+    private
+
+    def parse str
+      @media_type, str = consume_token str, downcase: true, error_message: "Failed to parse media type"
+      str = consume_special str, "/"
+      @subtype, str = consume_token str, downcase: true, error_message: "Failed to parse subtype"
+      @subtype_base, @subtype_format = @subtype.split "+", 2
+      until str.empty?
+        str = consume_special str, ";"
+        name, str = consume_token str, downcase: true, error_message: "Faled to parse attribute name"
+        str = consume_special str, "=", error_message: "Failed to find value for attribute #{name}"
+        val, str = consume_token_or_quoted str, error_message: "Failed to parse value for attribute #{name}"
+        @params << [name, val]
+        @charset = val if name == "charset"
+      end
+    rescue ParseError => e
+      @error_message = e.message
+    end
+
+    def consume_token str, downcase: false, error_message: nil
+      match = /^([\w!#\$%&'\*\+\.\^`\{\|\}-]+)(.*)$/.match str
+      raise ParseError, error_message || "Expected token" unless match
+      token = match[1]
+      token.downcase! if downcase
+      str = consume_comments match[2].strip
+      [token, str]
+    end
+
+    def consume_special str, expected, error_message: nil
+      raise ParseError, error_message || "Expected #{expected.inspect}" unless str.start_with? expected
+      consume_comments str[1..-1].strip
+    end
+
+    def consume_token_or_quoted str, error_message: nil
+      return consume_token str unless str.start_with? '"'
+      arr = []
+      index = 1
+      loop do
+        char = str[index]
+        case char
+        when nil
+          raise ParseError, error_message || "Quoted-string never finished"
+        when "\""
+          break
+        when "\\"
+          char = str[index + 1]
+          raise ParseError, error_message || "Quoted-string never finished" unless char
+          arr << char
+          index += 2
+        else
+          arr << char
+          index += 1
+        end
+      end
+      index += 1
+      str = consume_comments str[index..-1].strip
+      [arr.join, str]
+    end
+
+    def consume_comments str
+      return str unless str.start_with? "("
+      index = 1
+      loop do
+        char = str[index]
+        case char
+        when nil
+          raise ParseError, "Comment never finished"
+        when ")"
+          break
+        when "\\"
+          index += 2
+        when "("
+          str = consume_comments str[index..-1]
+          index = 0
+        else
+          index += 1
+        end
+      end
+      index += 1
+      consume_comments str[index..-1].strip
+    end
+
+    def maybe_quote str
+      return str if /^[\w!#\$%&'\*\+\.\^`\{\|\}-]+$/ =~ str
+      str = str.gsub("\\", "\\\\\\\\").gsub("\"", "\\\\\"")
+      "\"#{str}\""
+    end
+  end
+end

data/lib/cloud_events/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  ##
+  # Base class for all CloudEvents errors.
+  #
+  class CloudEventsError < ::StandardError
+  end
+
+  ##
+  # Errors indicating unsupported or incorrectly formatted HTTP content or
+  # headers.
+  #
+  class HttpContentError < CloudEventsError
+  end
+
+  ##
+  # Errors indicating an unsupported or incorrect spec version.
+  #
+  class SpecVersionError < CloudEventsError
+  end
+
+  ##
+  # Errors related to CloudEvent attributes.
+  #
+  class AttributeError < CloudEventsError
+  end
+end

data/lib/cloud_events/event.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "date"
+require "uri"
+
+require "cloud_events/event/field_interpreter"
+require "cloud_events/event/v0"
+require "cloud_events/event/v1"
+
+module CloudEvents
+  ##
+  # An Event object represents a complete CloudEvent, including both data and
+  # context attributes. The following are true of all event objects:
+  #
+  #  *  Event classes are defined within this module. For example, events
+  #     conforming to the CloudEvents 1.0 specification are of type
+  #     {CloudEvents::Event::V1}.
+  #  *  All event classes include this module, so you can use
+  #     `is_a? CloudEvents::Event` to test whether an object is an event.
+  #  *  All event objects are immutable. Data and atribute values can be
+  #     retrieved but not modified. To "modify" an event, make a copy with
+  #     the desired changes. Generally, event classes will provide a helper
+  #     method for this purpose.
+  #  *  All event objects have a `spec_version` method that returns the
+  #     version of the CloudEvents spec implemented by that event. (Other
+  #     methods may be different, depending on the spec version.)
+  #
+  # To create an event, you may either:
+  #
+  #  *  Construct an instance of the event class directly, for example by
+  #     calling {CloudEvents::Event::V1.new} and passing a set of attributes.
+  #  *  Call {CloudEvents::Event.create} and pass a spec version and a set of
+  #     attributes. This will choose the appropriate event class based on the
+  #     version.
+  #  *  Decode an event from another representation. For example, use
+  #     {CloudEvents::JsonFormat} to decode an event from JSON, or use
+  #     {CloudEvents::HttpBinding} to decode an event from an HTTP request.
+  #
+  # See https://github.com/cloudevents/spec for more information about
+  # CloudEvents. The documentation for the individual event classes
+  # {CloudEvents::Event::V0} and {CloudEvents::Event::V1} also include links to
+  # their respective specifications.
+  #
+  module Event
+    class << self
+      ##
+      # Create a new cloud event object with the given version. Generally,
+      # you must also pass additional keyword arguments providing the event's
+      # data and attributes. For example, if you pass `1.0` as the
+      # `spec_version`, the remaining keyword arguments will be passed
+      # through to the {CloudEvents::Event::V1} constructor.
+      #
+      # @param spec_version [String] The required `specversion` field.
+      # @param kwargs [keywords] Additional parameters for the event.
+      #
+      def create spec_version:, **kwargs
+        case spec_version
+        when "0.3"
+          V0.new spec_version: spec_version, **kwargs
+        when /^1(\.|$)/
+          V1.new spec_version: spec_version, **kwargs
+        else
+          raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
+        end
+      end
+      alias new create
+    end
+  end
+end

data/lib/cloud_events/event/field_interpreter.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  module Event
+    ##
+    # A helper that extracts and interprets event fields from an input hash.
+    #
+    # @private
+    #
+    class FieldInterpreter
+      def initialize args
+        @args = keys_to_strings args
+        @attributes = {}
+      end
+
+      def finish_attributes
+        @attributes.merge! @args
+        @args = {}
+        @attributes
+      end
+
+      def string keys, required: false
+        object keys, required: required do |value|
+          case value
+          when ::String
+            raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
+            [value, value]
+          else
+            raise AttributeError, "Illegal type for #{keys.first}:" \
+                                  " String expected but #{value.class} found"
+          end
+        end
+      end
+
+      def uri keys, required: false
+        object keys, required: required do |value|
+          case value
+          when ::String
+            raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
+            begin
+              [::URI.parse(value), value]
+            rescue ::URI::InvalidURIError => e
+              raise AttributeError, "Illegal format for #{keys.first}: #{e.message}"
+            end
+          when ::URI::Generic
+            [value, value.to_s]
+          else
+            raise AttributeError, "Illegal type for #{keys.first}:" \
+                                  " String or URI expected but #{value.class} found"
+          end
+        end
+      end
+
+      def rfc3339_date_time keys, required: false
+        object keys, required: required do |value|
+          case value
+          when ::String
+            begin
+              [::DateTime.rfc3339(value), value]
+            rescue ::Date::Error => e
+              raise AttributeError, "Illegal format for #{keys.first}: #{e.message}"
+            end
+          when ::DateTime
+            [value, value.rfc3339]
+          when ::Time
+            value = value.to_datetime
+            [value, value.rfc3339]
+          else
+            raise AttributeError, "Illegal type for #{keys.first}:" \
+                                  " String, Time, or DateTime expected but #{value.class} found"
+          end
+        end
+      end
+
+      def content_type keys, required: false
+        object keys, required: required do |value|
+          case value
+          when ::String
+            raise AttributeError, "The #{keys.first} field cannot be empty" if value.empty?
+            [ContentType.new(value), value]
+          when ContentType
+            [value, value.to_s]
+          else
+            raise AttributeError, "Illegal type for #{keys.first}:" \
+                                  " String, or ContentType expected but #{value.class} found"
+          end
+        end
+      end
+
+      def spec_version keys, accept:
+        object keys, required: true do |value|
+          case value
+          when ::String
+            raise SpecVersionError, "Unrecognized specversion: #{value}" unless accept =~ value
+            [value, value]
+          else
+            raise AttributeError, "Illegal type for #{keys.first}:" \
+                                  " String expected but #{value.class} found"
+          end
+        end
+      end
+
+      UNDEFINED = ::Object.new
+
+      def object keys, required: false, allow_nil: false
+        value = UNDEFINED
+        keys.each do |key|
+          key_present = @args.key? key
+          val = @args.delete key
+          value = val if allow_nil && key_present || !allow_nil && !val.nil?
+        end
+        if value == UNDEFINED
+          raise AttributeError, "The #{keys.first} field is required" if required
+          return nil
+        end
+        if block_given?
+          converted, raw = yield value
+        else
+          converted = raw = value
+        end
+        @attributes[keys.first] = raw
+        converted
+      end
+
+      private
+
+      def keys_to_strings hash
+        result = {}
+        hash.each do |key, val|
+          result[key.to_s] = val
+        end
+        result
+      end
+    end
+  end
+end