functions_framework 0.1.1 → 0.2.0

data/lib/functions_framework/cloud_events/event/v1.rb

@@ -0,0 +1,363 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "date"
+require "uri"
+
+module FunctionsFramework
+  module CloudEvents
+    module Event
+      ##
+      # A CloudEvents V1 data type.
+      #
+      # This object a complete CloudEvent, including the event data and its
+      # context attributes. It supports the standard required and optional
+      # attributes defined in CloudEvents V1, 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/master/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 # rubocop:disable Metrics/AbcSize
+          args = keys_to_strings(attributes || args)
+          @attributes = {}
+          @spec_version, _unused = interpret_string args, ["specversion", "spec_version"], required: true
+          raise SpecVersionError, "Unrecognized specversion: #{@spec_version}" unless /^1(\.|$)/ =~ @spec_version
+          @id, _unused = interpret_string args, ["id"], required: true
+          @source, @source_string = interpret_uri args, ["source"], required: true
+          @type, _unused = interpret_string args, ["type"], required: true
+          @data, _unused = interpret_value args, ["data"], allow_nil: true
+          @data_content_type, @data_content_type_string =
+            interpret_content_type args, ["datacontenttype", "data_content_type"]
+          @data_schema, @data_schema_string = interpret_uri args, ["dataschema", "data_schema"]
+          @subject, _unused = interpret_string args, ["subject"]
+          @time, @time_string = interpret_date_time args, ["time"]
+          @attributes.merge! args
+        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 keys_to_strings 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 what is returned from corresponding attribute
+        # methods. For example:
+        #
+        #     event["time"]     # => String rfc3339 representation
+        #     event.time        # => DateTime object
+        #     event.time_string # => String rfc3339 representation
+        #
+        # @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 string representation of the `source` field. Required.
+        #
+        # @return [String]
+        #
+        attr_reader :source_string
+
+        ##
+        # 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 String, boolean, Integer, Array, or
+        #     Hash
+        #
+        # @return [Object]
+        #
+        attr_reader :data
+
+        ##
+        # The optional `datacontenttype` field as a
+        # {FunctionsFramework::CloudEvents::ContentType} object, or `nil` if
+        # the field is absent.
+        #
+        # @return [FunctionsFramework::CloudEvents::ContentType,nil]
+        #
+        attr_reader :data_content_type
+        alias datacontenttype data_content_type
+
+        ##
+        # The string representation of the optional `datacontenttype` field, or
+        # `nil` if the field is absent.
+        #
+        # @return [String,nil]
+        #
+        attr_reader :data_content_type_string
+        alias datacontenttype_string data_content_type_string
+
+        ##
+        # 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 string representation of the optional `dataschema` field, or
+        # `nil` if the field is absent.
+        #
+        # @return [String,nil]
+        #
+        attr_reader :data_schema_string
+        alias dataschema_string data_schema_string
+
+        ##
+        # 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
+
+        ##
+        # The rfc3339 string representation of the optional `time` field, or
+        # `nil` if the field is absent.
+        #
+        # @return [String,nil]
+        #
+        attr_reader :time_string
+
+        ## @private
+        def == other
+          other.is_a?(V1) && @attributes == other.instance_variable_get(:@attributes)
+        end
+        alias eql? ==
+
+        ## @private
+        def hash
+          @hash ||= @attributes.hash
+        end
+
+        private
+
+        def keys_to_strings hash
+          result = {}
+          hash.each do |key, val|
+            result[key.to_s] = val
+          end
+          result
+        end
+
+        def interpret_string args, keys, required: false
+          interpret_value args, keys, required: required do |value|
+            case value
+            when ::String
+              raise AttributeError, "The #{keys.last} field cannot be empty" if value.empty?
+              [value, value]
+            else
+              raise AttributeError, "Illegal type for #{keys.last}:" \
+                                    " String expected but #{value.class} found"
+            end
+          end
+        end
+
+        def interpret_uri args, keys, required: false
+          interpret_value args, keys, required: required do |value|
+            case value
+            when ::String
+              raise AttributeError, "The #{keys.last} field cannot be empty" if value.empty?
+              begin
+                [::URI.parse(value), value]
+              rescue ::URI::InvalidURIError => e
+                raise AttributeError, "Illegal format for #{keys.last}: #{e.message}"
+              end
+            when ::URI::Generic
+              [value, value.to_s]
+            else
+              raise AttributeError, "Illegal type for #{keys.last}:" \
+                                    " String or URI expected but #{value.class} found"
+            end
+          end
+        end
+
+        def interpret_date_time args, keys, required: false
+          interpret_value args, keys, required: required do |value|
+            case value
+            when ::String
+              begin
+                [::DateTime.rfc3339(value), value]
+              rescue ::Date::Error => e
+                raise AttributeError, "Illegal format for #{keys.last}: #{e.message}"
+              end
+            when ::DateTime
+              [value, value.rfc3339]
+            when ::Time
+              value = value.to_datetime
+              [value, value.rfc3339]
+            else
+              raise AttributeError, "Illegal type for #{keys.last}:" \
+                                    " String, Time, or DateTime expected but #{value.class} found"
+            end
+          end
+        end
+
+        def interpret_content_type args, keys, required: false
+          interpret_value args, keys, required: required do |value|
+            case value
+            when ::String
+              raise AttributeError, "The #{keys.last} field cannot be empty" if value.empty?
+              [ContentType.new(value), value]
+            when ContentType
+              [value, value.to_s]
+            else
+              raise AttributeError, "Illegal type for #{keys.last}:" \
+                                    " String, or ContentType expected but #{value.class} found"
+            end
+          end
+        end
+
+        def interpret_value args, keys, required: false, allow_nil: false
+          value = nil
+          found = false
+          keys.each do |key|
+            key_present = args.key? key
+            val = args.delete key
+            if allow_nil && key_present || !allow_nil && !val.nil?
+              value = val
+              found = true
+            end
+          end
+          if found
+            if block_given?
+              converted, raw = yield value
+            else
+              converted = raw = value
+            end
+            @attributes[keys.first] = raw
+            [converted, raw]
+          else
+            raise AttributeError, "The #{keys.last} field is required" if required
+            [nil, nil]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/functions_framework/cloud_events/http_binding.rb

@@ -0,0 +1,270 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "functions_framework/cloud_events/json_format"
+
+module FunctionsFramework
+  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.
+    #
+    # See https://github.com/cloudevents/spec/blob/master/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
+      # {FunctionsFramework::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 {FunctionsFramework::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 [FunctionsFramework::CloudEvents::Event] if the request
+      #     includes a single structured or binary event.
+      # @return [Array<FunctionsFramework::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_prefix
+          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 [FunctionsFramework::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<FunctionsFramework::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 [FunctionsFramework::CloudEvents::ContentType]
+      #     the content type from the Rack environment.
+      # @return [FunctionsFramework::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] = 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 [FunctionsFramework::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<FunctionsFramework::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 [FunctionsFramework::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}"] = 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
+    end
+  end
+end