functions_framework 0.0.0 → 0.1.0

data/lib/functions_framework/cloud_events/event.rb

@@ -0,0 +1,277 @@
+# 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
+    ##
+    # A cloud event data type.
+    #
+    # 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.
+    #
+    # See https://github.com/cloudevents/spec/blob/master/spec.md for
+    # descriptions of the various attributes.
+    #
+    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}"
+        end
+      end
+    end
+  end
+end

data/lib/functions_framework/cloud_events/json_structure.rb

@@ -0,0 +1,88 @@
+# 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 "base64"
+require "json"
+
+module FunctionsFramework
+  module CloudEvents
+    ##
+    # A content handler for the JSON structure and JSON batch format.
+    # See https://github.com/cloudevents/spec/blob/master/json-format.md
+    #
+    module JsonStructure
+      class << self
+        ##
+        # Decode an event from the given input string
+        #
+        # @param input [IO] An IO-like object providing a JSON-formatted string
+        # @param content_type [FunctionsFramework::CloudEvents::ContentType]
+        #     the content type
+        # @return [FunctionsFramework::CloudEvents::Event]
+        #
+        def decode_structured_content input, content_type
+          input = input.read if input.respond_to? :read
+          charset = content_type.charset
+          input = input.encode charset if charset
+          structure = ::JSON.parse input
+          decode_hash_structure structure
+        end
+
+        ##
+        # Decode a batch of events from the given input string
+        #
+        # @param input [IO] An IO-like object providing a JSON-formatted string
+        # @param content_type [FunctionsFramework::CloudEvents::ContentType]
+        #     the content type
+        # @return [Array<FunctionsFramework::CloudEvents::Event>]
+        #
+        def decode_batched_content input, content_type
+          input = input.read if input.respond_to? :read
+          charset = content_type.charset
+          input = input.encode charset if charset
+          structure_array = Array(::JSON.parse(input))
+          structure_array.map { |structure| decode_hash_structure structure }
+        end
+
+        ##
+        # Decode a single event from a hash data structure with keys and types
+        # conforming to the JSON event format
+        #
+        # @param structure [Hash] Input hash
+        # @return [FunctionsFramework::CloudEvents::Event]
+        #
+        def decode_hash_structure structure
+          data =
+            if structure.key? "data_base64"
+              ::Base64.decode64 structure["data_base64"]
+            else
+              structure["data"]
+            end
+          spec_version = structure["specversion"]
+          raise "Unrecognized specversion: #{spec_version}" unless spec_version == "1.0"
+          Event.new \
+            id:                structure["id"],
+            source:            structure["source"],
+            type:              structure["type"],
+            spec_version:      spec_version,
+            data:              data,
+            data_content_type: structure["datacontenttype"],
+            data_schema:       structure["dataschema"],
+            subject:           structure["subject"],
+            time:              structure["time"]
+        end
+      end
+    end
+  end
+end

data/lib/functions_framework/cloud_events.rb

@@ -0,0 +1,143 @@
+# 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/binary_content"
+require "functions_framework/cloud_events/content_type"
+require "functions_framework/cloud_events/event"
+
+module FunctionsFramework
+  ##
+  # CloudEvents implementation.
+  #
+  # This is a Ruby implementation of the [CloudEvents](https://cloudevents.io)
+  # [1.0 specification](https://github.com/cloudevents/spec/blob/master/spec.md).
+  # It provides for unmarshaling of events from Rack environment data from
+  # binary (i.e. header-based) format, as well as structured (body-based) and
+  # batch formats. A standard JSON structure parser is included. It is also
+  # possible to register handlers for other formats.
+  #
+  # TODO: Unmarshaling of events is implemented, but marshaling is not.
+  #
+  module CloudEvents
+    @structured_formats = {}
+    @batched_formats = {}
+
+    class << self
+      ##
+      # Register a handler for the given structured format.
+      # The handler object must respond to the method
+      # `#decode_structured_content`. See
+      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
+      #
+      # @param format [String] The subtype format that should be handled by
+      #     this handler
+      # @param handler [#decode_structured_content] The handler object
+      # @return [self]
+      #
+      def register_structured_format format, handler
+        handlers = @structured_formats[format.to_s.strip.downcase] ||= []
+        handlers << handler unless handlers.include? handler
+        self
+      end
+
+      ##
+      # Register a handler for the given batched format.
+      # The handler object must respond to the method
+      # `#decode_batched_content`. See
+      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
+      #
+      # @param format [String] The subtype format that should be handled by
+      #     this handler
+      # @param handler [#decode_batched_content] The handler object
+      # @return [self]
+      #
+      def register_batched_format format, handler
+        handlers = @batched_formats[format.to_s.strip.downcase] ||= []
+        handlers << handler unless handlers.include? handler
+        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
+      # @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
+      #
+      def decode_rack_env env
+        content_type_header = env["CONTENT_TYPE"]
+        raise "Missing content-type header" unless content_type_header
+        content_type = ContentType.new content_type_header
+        if content_type.media_type == "application"
+          case content_type.subtype_prefix
+          when "cloudevents"
+            return decode_structured_content env["rack.input"], content_type
+          when "cloudevents-batch"
+            return decode_batched_content env["rack.input"], content_type
+          end
+        end
+        BinaryContent.decode_rack_env 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 [IO] An IO-like object providing the content
+      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
+      #     content type
+      # @return [FunctionsFramework::CloudEvents::Event]
+      #
+      def decode_structured_content input, content_type
+        handlers = @structured_formats[content_type.subtype_format] || []
+        handlers.reverse_each do |handler|
+          event = handler.decode_structured_content input, content_type
+          return event if event
+        end
+        raise "Unknown cloudevents format: #{content_type.subtype_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 [IO] An IO-like object providing the content
+      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
+      #     content type
+      # @return [Array<FunctionsFramework::CloudEvents::Event>]
+      #
+      def decode_batched_content input, content_type
+        handlers = @batched_formats[content_type.subtype_format] || []
+        handlers.reverse_each do |handler|
+          events = handler.decode_batched_content input, content_type
+          return events if events
+        end
+        raise "Unknown cloudevents batch format: #{content_type.subtype_format.inspect}"
+      end
+    end
+  end
+end
+
+require "functions_framework/cloud_events/json_structure"
+
+FunctionsFramework::CloudEvents.register_structured_format \
+  "json", FunctionsFramework::CloudEvents::JsonStructure
+FunctionsFramework::CloudEvents.register_batched_format \
+  "json", FunctionsFramework::CloudEvents::JsonStructure

data/lib/functions_framework/function.rb

@@ -0,0 +1,75 @@
+# 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
+  ##
+  # Representation of a function.
+  #
+  # A function has a name, a type, and a code definition.
+  #
+  class Function
+    ##
+    # Create a new function definition.
+    #
+    # @param name [String] The function name
+    # @param type [Symbol] The type of function. Valid types are
+    #     `:http`, `:event`, and `:cloud_event`.
+    # @param block [Proc] The function code as a proc
+    #
+    def initialize name, type, &block
+      @name = name
+      @type = type
+      @block = block
+    end
+
+    ##
+    # @return [String] The function name
+    #
+    attr_reader :name
+
+    ##
+    # @return [Symbol] The function type
+    #
+    attr_reader :type
+
+    ##
+    # @return [Proc] The function code as a proc
+    #
+    attr_reader :block
+
+    ##
+    # Call the function. You must pass an argument appropriate to the type
+    # of function.
+    #
+    #  *  A `:http` type function takes a `Rack::Request` argument, and returns
+    #     a Rack response type. See {FunctionsFramework::Registry.add_http}.
+    #  *  A `:event` or `:cloud_event` type function takes a
+    #     {FunctionsFramework::CloudEvents::Event} argument, and does not
+    #     return a value. See {FunctionsFramework::Registry.add_cloud_event}.
+    #     Note that for an `:event` type function, the passed event argument is
+    #     split into two arguments when passed to the underlying block.
+    #
+    # @param argument [Rack::Request,FunctionsFramework::CloudEvents::Event]
+    # @return [Object]
+    #
+    def call argument
+      case type
+      when :event
+        block.call argument.data, argument
+      else
+        block.call argument
+      end
+    end
+  end
+end