functions_framework 0.1.1 → 0.4.0

data/lib/functions_framework/cloud_events/errors.rb

@@ -0,0 +1,42 @@
+# 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.
+
+module FunctionsFramework
+  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
+end

data/lib/functions_framework/cloud_events/event.rb

@@ -15,262 +15,69 @@
 require "date"
 require "uri"
 
+require "functions_framework/cloud_events/event/field_interpreter"
+require "functions_framework/cloud_events/event/v0"
+require "functions_framework/cloud_events/event/v1"
+
 module FunctionsFramework
   module CloudEvents
     ##
-    # A cloud event data type.
+    # An Event object represents a complete CloudEvent, including both data and
+    # context attributes. The following are true of all event objects:
     #
-    # This object represents both the event data and the context attributes.
-    # It 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.
+    #  *  Event classes are defined within this module. For example, events
+    #     conforming to the CloudEvents 1.0 specification are of type
+    #     {FunctionsFramework::CloudEvents::Event::V1}.
+    #  *  All event classes include this module, so you can use
+    #     `is_a? FunctionsFramework::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.)
     #
-    # See https://github.com/cloudevents/spec/blob/master/spec.md for
-    # descriptions of the various attributes.
+    # To create an event, you may either:
     #
-    class Event
-      ##
-      # Create a new cloud event object with the given data and attributes.
-      #
-      # @param id [String] The required `id` field
-      # @param source [String,URI] The required `source` field
-      # @param type [String] The required `type` field
-      # @param spec_version [String] The required `specversion` field
-      # @param data [String,Boolean,Integer,Array,Hash] The optional `data`
-      #     field
-      # @param data_content_type [String,FunctionsFramework::CloudEvents::ContentType]
-      #     The optional `datacontenttype` field
-      # @param data_schema [String,URI] The optional `dataschema` field
-      # @param subject [String] The optional `subject` field
-      # @param time [String,DateTime] The optional `time` field
-      #
-      def initialize \
-          id:,
-          source:,
-          type:,
-          spec_version:,
-          data: nil,
-          data_content_type: nil,
-          data_schema: nil,
-          subject: nil,
-          time: nil
-        @id = interpret_string "id", id, true
-        @source, @source_string = interpret_uri "source", source, true
-        @type = interpret_string "type", type, true
-        @spec_version = interpret_string "spec_version", spec_version, true
-        @data = data
-        @data_content_type, @data_content_type_string =
-          interpret_content_type "data_content_type", data_content_type
-        @data_schema, @data_schema_string = interpret_uri "data_schema", data_schema
-        @subject = interpret_string "subject", subject
-        @time, @time_string = interpret_date_time "time", time
-      end
-
-      ##
-      # Create and return a copy of this event with the given changes. See the
-      # constructor for the parameters that can be passed.
-      #
-      # @param changes [keywords] See {#initialize} for a list of arguments.
-      # @return [FunctionFramework::CloudEvents::Event]
-      #
-      def with **changes
-        params = {
-          id:                id,
-          source:            source,
-          type:              type,
-          spec_version:      spec_version,
-          data:              data,
-          data_content_type: data_content_type,
-          data_schema:       data_schema,
-          subject:           subject,
-          time:              time
-        }
-        params.merge! changes
-        Event.new(**params)
-      end
-
-      ##
-      # The `id` field
-      # @return [String]
-      #
-      attr_reader :id
-
-      ##
-      # The `source` field as a `URI` object
-      # @return [URI]
-      #
-      attr_reader :source
-
-      ##
-      # The string representation of the `source` field
-      # @return [String]
-      #
-      attr_reader :source_string
-
-      ##
-      # The `type` field
-      # @return [String]
-      #
-      attr_reader :type
-
-      ##
-      # The `specversion` field
-      # @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 `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 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?(ContentType) &&
-          id == other.id &&
-          source == other.source &&
-          type == other.type &&
-          spec_version == other.spec_version &&
-          data_content_type == other.data_content_type &&
-          data_schema == other.data_schema &&
-          subject == other.subject &&
-          time == other.time &&
-          data == other.data
-      end
-      alias eql? ==
-
-      ## @private
-      def hash
-        @hash ||=
-          [id, source, type, spec_version, data_content_type, data_schema, subject, time, data].hash
-      end
-
-      private
-
-      def interpret_string name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          input
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          nil
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
-        end
-      end
-
-      def interpret_uri name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          [::URI.parse(input), input]
-        when ::URI::Generic
-          [input, input.to_s]
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          [nil, nil]
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
-        end
-      end
-
-      def interpret_date_time name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          [::DateTime.rfc3339(input), input]
-        when ::DateTime
-          [input, input.rfc3339]
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          [nil, nil]
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
-        end
-      end
-
-      def interpret_content_type name, input, required = false
-        case input
-        when ::String
-          raise ::ArgumentError, "The #{name} field cannot be empty" if input.empty?
-          [ContentType.new(input), input]
-        when ContentType
-          [input, input.to_s]
-        when nil
-          raise ::ArgumentError, "The #{name} field is required" if required
-          [nil, nil]
-        else
-          raise ::ArgumentError, "Illegal type for #{name} field: #{input.inspect}"
+    #  *  Construct an instance of the event class directly, for example by
+    #     calling {Event::V1.new} and passing a set of attributes.
+    #  *  Call {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
+    # {FunctionsFramework::CloudEvents::Event::V0} and
+    # {FunctionsFramework::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 {Event::V1.new} 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/functions_framework/cloud_events/event/field_interpreter.rb

@@ -0,0 +1,150 @@
+# 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.
+
+module FunctionsFramework
+  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
+end