cloud_events 0.1.0

data/lib/cloud_events/event/v0.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "date"
+require "uri"
+
+module CloudEvents
+  module Event
+    ##
+    # A CloudEvents V0 data type.
+    #
+    # This object represents a complete CloudEvent, including the event data
+    # and context attributes. It supports the standard required and optional
+    # attributes defined in CloudEvents V0.3, and arbitrary extension
+    # attributes. All attribute values can be obtained (in their string form)
+    # via the {Event::V0#[]} method. Additionally, standard attributes have
+    # 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.
+    #
+    # See https://github.com/cloudevents/spec/blob/v0.3/spec.md for
+    # descriptions of the standard attributes.
+    #
+    class V0
+      include Event
+
+      ##
+      # Create a new cloud event object with the given data and attributes.
+      #
+      # Event attributes may be presented as keyword arguments, or as a Hash
+      # passed in via the `attributes` argument (but not both).
+      #
+      # The following standard attributes are supported and exposed as
+      # attribute methods on the object.
+      #
+      #  *  **:spec_version** (or **:specversion**) [`String`] - _required_ -
+      #     The CloudEvents spec version (i.e. the `specversion` field.)
+      #  *  **:id** [`String`] - _required_ - The event `id` field.
+      #  *  **:source** [`String`, `URI`] - _required_ - The event `source`
+      #     field.
+      #  *  **:type** [`String`] - _required_ - The event `type` field.
+      #  *  **:data** [`Object`] - _optional_ - The data associated with the
+      #     event (i.e. the `data` field.)
+      #  *  **:data_content_encoding** (or **:datacontentencoding**)
+      #     [`String`] - _optional_ - The content-encoding for the data (i.e.
+      #     the `datacontentencoding` 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.)
+      #  *  **:schema_url** (or **:schemaurl**) [`String`, `URI`] -
+      #     _optional_ - The event `schemaurl` field.
+      #  *  **:subject** [`String`] - _optional_ - The event `subject` field.
+      #  *  **:time** [`String`, `DateTime`, `Time`] - _optional_ - The
+      #     event `time` field.
+      #
+      # Any additional attributes are assumed to be extension attributes.
+      # They are not available as separate methods, but can be accessed via
+      # the {Event::V1#[]} operator.
+      #
+      # @param attributes [Hash] The data and attributes, as a hash.
+      # @param args [keywords] The data and attributes, as keyword arguments.
+      #
+      def initialize attributes: nil, **args
+        interpreter = FieldInterpreter.new attributes || args
+        @spec_version = interpreter.spec_version ["specversion", "spec_version"], accept: /^0\.3$/
+        @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_content_encoding = interpreter.string ["datacontentencoding", "data_content_encoding"]
+        @data_content_type = interpreter.content_type ["datacontenttype", "data_content_type"]
+        @schema_url = interpreter.uri ["schemaurl", "schema_url"]
+        @subject = interpreter.string ["subject"]
+        @time = interpreter.rfc3339_date_time ["time"]
+        @attributes = interpreter.finish_attributes
+      end
+
+      ##
+      # Create and return a copy of this event with the given changes. See
+      # the constructor for the parameters that can be passed. In general,
+      # you can pass a new value for any attribute, or pass `nil` to remove
+      # an optional attribute.
+      #
+      # @param changes [keywords] See {#initialize} for a list of arguments.
+      # @return [FunctionFramework::CloudEvents::Event]
+      #
+      def with **changes
+        attributes = @attributes.merge changes
+        V0.new attributes: attributes
+      end
+
+      ##
+      # Return the value of the given named attribute. Both standard and
+      # extension attributes are supported.
+      #
+      # Attribute names must be given as defined in the standard CloudEvents
+      # specification. For example `specversion` rather than `spec_version`.
+      #
+      # Results are given in their "raw" form, generally a string. This may
+      # be different from the Ruby object returned from corresponding
+      # attribute methods. For example:
+      #
+      #     event["time"]     # => String rfc3339 representation
+      #     event.time        # => DateTime object
+      #
+      # @param key [String,Symbol] The attribute name.
+      # @return [String,nil]
+      #
+      def [] key
+        @attributes[key.to_s]
+      end
+
+      ##
+      # Return a hash representation of this event.
+      #
+      # @return [Hash]
+      #
+      def to_h
+        @attributes.dup
+      end
+
+      ##
+      # The `id` field. Required.
+      #
+      # @return [String]
+      #
+      attr_reader :id
+
+      ##
+      # The `source` field as a `URI` object. Required.
+      #
+      # @return [URI]
+      #
+      attr_reader :source
+
+      ##
+      # The `type` field. Required.
+      #
+      # @return [String]
+      #
+      attr_reader :type
+
+      ##
+      # The `specversion` field. Required.
+      #
+      # @return [String]
+      #
+      attr_reader :spec_version
+      alias specversion spec_version
+
+      ##
+      # The event-specific data, or `nil` if there is no data.
+      #
+      # Data may be one of the following types:
+      #  *  Binary data, represented by a `String` using the `ASCII-8BIT`
+      #     encoding.
+      #  *  A string in some other encoding such as `UTF-8` or `US-ASCII`.
+      #  *  Any JSON data type, such as a Boolean, Integer, Array, Hash, or
+      #     `nil`.
+      #
+      # @return [Object]
+      #
+      attr_reader :data
+
+      ##
+      # The optional `datacontentencoding` field as a `String` object, or
+      # `nil` if the field is absent.
+      #
+      # @return [String,nil]
+      #
+      attr_reader :data_content_encoding
+      alias datacontentencoding data_content_encoding
+
+      ##
+      # The optional `datacontenttype` field as a {CloudEvents::ContentType}
+      # object, or `nil` if the field is absent.
+      #
+      # @return [CloudEvents::ContentType,nil]
+      #
+      attr_reader :data_content_type
+      alias datacontenttype data_content_type
+
+      ##
+      # The optional `schemaurl` field as a `URI` object, or `nil` if the
+      # field is absent.
+      #
+      # @return [URI,nil]
+      #
+      attr_reader :schema_url
+      alias schemaurl schema_url
+
+      ##
+      # The optional `subject` field, or `nil` if the field is absent.
+      #
+      # @return [String,nil]
+      #
+      attr_reader :subject
+
+      ##
+      # The optional `time` field as a `DateTime` object, or `nil` if the
+      # field is absent.
+      #
+      # @return [DateTime,nil]
+      #
+      attr_reader :time
+
+      ## @private
+      def == other
+        other.is_a?(V1) && @attributes == other.instance_variable_get(:@attributes)
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        @hash ||= @attributes.hash
+      end
+    end
+  end
+end

data/lib/cloud_events/event/v1.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "date"
+require "uri"
+
+module CloudEvents
+  module Event
+    ##
+    # A CloudEvents V1 data type.
+    #
+    # This object represents a complete CloudEvent, including the event data
+    # and context attributes. It supports the standard required and optional
+    # attributes defined in CloudEvents V1.0, and arbitrary extension
+    # attributes. All attribute values can be obtained (in their string form)
+    # via the {Event::V1#[]} method. Additionally, standard attributes have
+    # 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.
+    #
+    # See https://github.com/cloudevents/spec/blob/v1.0/spec.md for
+    # descriptions of the standard attributes.
+    #
+    class V1
+      include Event
+
+      ##
+      # Create a new cloud event object with the given data and attributes.
+      #
+      # Event attributes may be presented as keyword arguments, or as a Hash
+      # passed in via the `attributes` argument (but not both).
+      #
+      # The following standard attributes are supported and exposed as
+      # attribute methods on the object.
+      #
+      #  *  **:spec_version** (or **:specversion**) [`String`] - _required_ -
+      #     The CloudEvents spec version (i.e. the `specversion` field.)
+      #  *  **:id** [`String`] - _required_ - The event `id` field.
+      #  *  **:source** [`String`, `URI`] - _required_ - The event `source`
+      #     field.
+      #  *  **:type** [`String`] - _required_ - The event `type` field.
+      #  *  **:data** [`Object`] - _optional_ - The data associated with the
+      #     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.)
+      #  *  **:data_schema** (or **:dataschema**) [`String`, `URI`] -
+      #     _optional_ - The event `dataschema` field.
+      #  *  **:subject** [`String`] - _optional_ - The event `subject` field.
+      #  *  **:time** [`String`, `DateTime`, `Time`] - _optional_ - The
+      #     event `time` field.
+      #
+      # Any additional attributes are assumed to be extension attributes.
+      # They are not available as separate methods, but can be accessed via
+      # the {Event::V1#[]} operator.
+      #
+      # @param attributes [Hash] The data and attributes, as a hash.
+      # @param args [keywords] The data and attributes, as keyword arguments.
+      #
+      def initialize attributes: nil, **args
+        interpreter = FieldInterpreter.new attributes || args
+        @spec_version = interpreter.spec_version ["specversion", "spec_version"], accept: /^1(\.|$)/
+        @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_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
+      end
+
+      ##
+      # Create and return a copy of this event with the given changes. See
+      # the constructor for the parameters that can be passed. In general,
+      # you can pass a new value for any attribute, or pass `nil` to remove
+      # an optional attribute.
+      #
+      # @param changes [keywords] See {#initialize} for a list of arguments.
+      # @return [FunctionFramework::CloudEvents::Event]
+      #
+      def with **changes
+        attributes = @attributes.merge changes
+        V1.new attributes: attributes
+      end
+
+      ##
+      # Return the value of the given named attribute. Both standard and
+      # extension attributes are supported.
+      #
+      # Attribute names must be given as defined in the standard CloudEvents
+      # specification. For example `specversion` rather than `spec_version`.
+      #
+      # Results are given in their "raw" form, generally a string. This may
+      # be different from the Ruby object returned from corresponding
+      # attribute methods. For example:
+      #
+      #     event["time"]     # => String rfc3339 representation
+      #     event.time        # => DateTime object
+      #
+      # @param key [String,Symbol] The attribute name.
+      # @return [String,nil]
+      #
+      def [] key
+        @attributes[key.to_s]
+      end
+
+      ##
+      # Return a hash representation of this event.
+      #
+      # @return [Hash]
+      #
+      def to_h
+        @attributes.dup
+      end
+
+      ##
+      # The `id` field. Required.
+      #
+      # @return [String]
+      #
+      attr_reader :id
+
+      ##
+      # The `source` field as a `URI` object. Required.
+      #
+      # @return [URI]
+      #
+      attr_reader :source
+
+      ##
+      # The `type` field. Required.
+      #
+      # @return [String]
+      #
+      attr_reader :type
+
+      ##
+      # The `specversion` field. Required.
+      #
+      # @return [String]
+      #
+      attr_reader :spec_version
+      alias specversion spec_version
+
+      ##
+      # The event-specific data, or `nil` if there is no data.
+      #
+      # Data may be one of the following types:
+      #  *  Binary data, represented by a `String` using the `ASCII-8BIT`
+      #     encoding.
+      #  *  A string in some other encoding such as `UTF-8` or `US-ASCII`.
+      #  *  Any JSON data type, such as a Boolean, Integer, Array, Hash, or
+      #     `nil`.
+      #
+      # @return [Object]
+      #
+      attr_reader :data
+
+      ##
+      # The optional `datacontenttype` field as a {CloudEvents::ContentType}
+      # object, or `nil` if the field is absent.
+      #
+      # @return [CloudEvents::ContentType,nil]
+      #
+      attr_reader :data_content_type
+      alias datacontenttype data_content_type
+
+      ##
+      # The optional `dataschema` field as a `URI` object, or `nil` if the
+      # field is absent.
+      #
+      # @return [URI,nil]
+      #
+      attr_reader :data_schema
+      alias dataschema data_schema
+
+      ##
+      # The optional `subject` field, or `nil` if the field is absent.
+      #
+      # @return [String,nil]
+      #
+      attr_reader :subject
+
+      ##
+      # The optional `time` field as a `DateTime` object, or `nil` if the
+      # field is absent.
+      #
+      # @return [DateTime,nil]
+      #
+      attr_reader :time
+
+      ## @private
+      def == other
+        other.is_a?(V1) && @attributes == other.instance_variable_get(:@attributes)
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        @hash ||= @attributes.hash
+      end
+    end
+  end
+end

data/lib/cloud_events/http_binding.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module CloudEvents
+  ##
+  # HTTP binding for CloudEvents.
+  #
+  # This class implements HTTP binding, including unmarshalling of events from
+  # Rack environment data, and marshalling of events to Rack environment data.
+  # It supports binary (i.e. header-based) HTTP content, as well as structured
+  # (body-based) content that can delegate to formatters such as JSON.
+  #
+  # Supports the CloudEvents 0.3 and CloudEvents 1.0 variants of this format.
+  # See https://github.com/cloudevents/spec/blob/v0.3/http-transport-binding.md
+  # and https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md.
+  #
+  class HttpBinding
+    ##
+    # Returns a default binding, with JSON supported.
+    #
+    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
+      end
+    end
+
+    ##
+    # Create an empty HTTP binding.
+    #
+    def initialize
+      @structured_formatters = {}
+      @batched_formatters = {}
+    end
+
+    ##
+    # Register a formatter for the given type.
+    #
+    # 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.
+    # @return [self]
+    #
+    def register_structured_formatter type, formatter
+      formatters = @structured_formatters[type.to_s.strip.downcase] ||= []
+      formatters << formatter unless formatters.include? formatter
+      self
+    end
+
+    ##
+    # Register a batch formatter for the given type.
+    #
+    # A batch formatter must respond to the methods `#encode_batch` and
+    # `#decode_batch`. See {CloudEvents::JsonFormat} for an example.
+    #
+    # @param type [String] The subtype format that should be handled by
+    #     this formatter.
+    # @param formatter [Object] The formatter object.
+    # @return [self]
+    #
+    def register_batched_formatter type, formatter
+      formatters = @batched_formatters[type.to_s.strip.downcase] ||= []
+      formatters << formatter unless formatters.include? formatter
+      self
+    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.
+    #
+    # @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 was not recognized as a CloudEvent.
+    #
+    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
+      end
+      decode_binary_content env, content_type
+    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`.
+    #
+    # @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]
+    #
+    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`.
+    #
+    # @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 [Array<CloudEvents::Event>]
+    #
+    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
+      end
+      raise HttpContentError, "Unknown cloudevents batch format: #{format.inspect}"
+    end
+
+    ##
+    # Decode an event from the given Rack environment in binary content mode.
+    #
+    # @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
+    #
+    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
+    end
+
+    ##
+    # Encode a single event to content data 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`.
+    #
+    # @param event [CloudEvents::Event] The event.
+    # @param format [String] The format code (e.g. "json")
+    # @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
+      end
+      raise HttpContentError, "Unknown cloudevents format: #{format.inspect}"
+    end
+
+    ##
+    # Encode a batch of events to content data 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`.
+    #
+    # @param events [Array<CloudEvents::Event>] The batch of events.
+    # @param format [String] The format code (e.g. "json").
+    # @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
+      end
+      raise HttpContentError, "Unknown cloudevents format: #{format.inspect}"
+    end
+
+    ##
+    # Encode an event to content and headers, 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.
+    #
+    # @param event [CloudEvents::Event] The event.
+    # @return [Array(headers,String)]
+    #
+    def encode_binary_content event
+      headers = {}
+      body = nil
+      event.to_h.each do |key, value|
+        if key == "data"
+          body = value
+        elsif key == "datacontenttype"
+          headers["Content-Type"] = value
+        else
+          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"
+      else
+        body = ::JSON.dump body
+        headers["Content-Type"] ||= "application/json; charset=#{body.encoding.name.downcase}"
+      end
+      [headers, body]
+    end
+
+    ##
+    # Decode a percent-encoded string to a UTF-8 string.
+    #
+    # @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
+      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
+
+    ##
+    # Transcode an arbitrarily-encoded string to UTF-8, then percent-encode
+    # non-printing and non-ascii characters to result in an ASCII string
+    # suitable for setting as an HTTP header value.
+    #
+    # @param str [String] Incoming arbitrary string that can be represented
+    #     in UTF-8.
+    # @return [String] Resulting encoded string in ASCII.
+    #
+    def percent_encode str
+      arr = []
+      utf_str = str.to_s.encode ::Encoding::UTF_8
+      utf_str.each_byte do |byte|
+        if byte >= 33 && byte <= 126 && byte != 37
+          arr << byte
+        else
+          hi = byte / 16
+          hi = hi > 9 ? 55 + hi : 48 + hi
+          lo = byte % 16
+          lo = lo > 9 ? 55 + lo : 48 + lo
+          arr << 37 << hi << lo
+        end
+      end
+      arr.pack "C*"
+    end
+  end
+end