functions_framework 0.3.1 → 0.4.0

data/lib/functions_framework/cloud_events/http_binding.rb

@@ -24,7 +24,9 @@ module FunctionsFramework
     # 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
+    # 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
       ##
@@ -101,7 +103,7 @@ module FunctionsFramework
         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
+          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
@@ -177,7 +179,7 @@ module FunctionsFramework
           match = /^HTTP_CE_(\w+)$/.match key
           next unless match
           attr_name = match[1].downcase
-          attributes[attr_name] = value unless omit_names.include? attr_name
+          attributes[attr_name] = percent_decode value unless omit_names.include? attr_name
         end
         Event.create spec_version: spec_version, attributes: attributes
       end
@@ -248,7 +250,7 @@ module FunctionsFramework
           elsif key == "datacontenttype"
             headers["Content-Type"] = value
           else
-            headers["CE-#{key}"] = value
+            headers["CE-#{key}"] = percent_encode value
           end
         end
         if body.is_a? ::String
@@ -265,6 +267,44 @@ module FunctionsFramework
         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
 end

data/lib/functions_framework/cloud_events/json_format.rb

@@ -20,7 +20,9 @@ module FunctionsFramework
     ##
     # An implementation of JSON format and JSON batch format.
     #
-    # See https://github.com/cloudevents/spec/blob/master/json-format.md
+    # Supports the CloudEvents 0.3 and CloudEvents 1.0 variants of this format.
+    # See https://github.com/cloudevents/spec/blob/v0.3/json-format.md and
+    # https://github.com/cloudevents/spec/blob/v1.0/json-format.md.
     #
     class JsonFormat
       ##
@@ -78,34 +80,39 @@ module FunctionsFramework
 
       ##
       # Decode a single event from a hash data structure with keys and types
-      # conforming to the JSON event format.
+      # conforming to the JSON envelope.
       #
       # @param structure [Hash] An input hash.
       # @return [FunctionsFramework::CloudEvents::Event]
       #
       def decode_hash_structure structure
-        if structure.key? "data_base64"
-          structure = structure.dup
-          structure["data"] = ::Base64.decode64 structure.delete "data_base64"
+        spec_version = structure["specversion"].to_s
+        case spec_version
+        when "0.3"
+          decode_hash_structure_v0 structure
+        when /^1(\.|$)/
+          decode_hash_structure_v1 structure
+        else
+          raise SpecVersionError, "Unrecognized specversion: #{spec_version}"
         end
-        Event.create spec_version: structure["specversion"], attributes: structure
       end
 
       ##
       # Encode a single event to a hash data structure with keys and types
-      # conforming to the JSON event format.
+      # conforming to the JSON envelope.
       #
       # @param event [FunctionsFramework::CloudEvents::Event] An input event.
       # @return [String] The hash structure.
       #
       def encode_hash_structure event
-        structure = event.to_h
-        data = structure["data"]
-        if data.is_a?(::String) && data.encoding == ::Encoding::ASCII_8BIT
-          structure.delete "data"
-          structure["data_base64"] = ::Base64.encode64 data
+        case event
+        when Event::V0
+          encode_hash_structure_v0 event
+        when Event::V1
+          encode_hash_structure_v1 event
+        else
+          raise SpecVersionError, "Unrecognized specversion: #{event.spec_version}"
         end
-        structure
       end
 
       private
@@ -117,6 +124,50 @@ module FunctionsFramework
         end
         result
       end
+
+      def decode_hash_structure_v0 structure
+        data = structure["data"]
+        content_type = structure["datacontenttype"]
+        if data.is_a?(::String) && content_type.is_a?(::String)
+          content_type = ContentType.new content_type
+          if content_type.subtype == "json" || content_type.subtype_format == "json"
+            structure = structure.dup
+            structure["data"] = ::JSON.parse data rescue data
+            structure["datacontenttype"] = content_type
+          end
+        end
+        Event::V0.new attributes: structure
+      end
+
+      def decode_hash_structure_v1 structure
+        if structure.key? "data_base64"
+          structure = structure.dup
+          structure["data"] = ::Base64.decode64 structure.delete "data_base64"
+        end
+        Event::V1.new attributes: structure
+      end
+
+      def encode_hash_structure_v0 event
+        structure = event.to_h
+        data = event.data
+        content_type = event.data_content_type
+        if data.is_a?(::String) && !content_type.nil?
+          if content_type.subtype == "json" || content_type.subtype_format == "json"
+            structure["data"] = ::JSON.parse data rescue data
+          end
+        end
+        structure
+      end
+
+      def encode_hash_structure_v1 event
+        structure = event.to_h
+        data = structure["data"]
+        if data.is_a?(::String) && data.encoding == ::Encoding::ASCII_8BIT
+          structure.delete "data"
+          structure["data_base64"] = ::Base64.encode64 data
+        end
+        structure
+      end
     end
   end
 end

data/lib/functions_framework/function.rb

@@ -16,22 +16,58 @@ module FunctionsFramework
   ##
   # Representation of a function.
   #
-  # A function has a name, a type, and a code definition.
+  # A function has a name, a type, and an implementation.
+  #
+  # The implementation in general is an object that responds to the `call`
+  # method. For a function of type `:http`, the `call` method takes a single
+  # `Rack::Request` argument and returns one of various HTTP response types.
+  # See {FunctionsFramework::Registry.add_http}. For a function of type
+  # `:cloud_event`, the `call` method takes a single
+  # {FunctionsFramework::CloudEvents::Event CloudEvent} argument, and does not
+  # return a value. See {FunctionsFramework::Registry.add_cloud_event}.
+  #
+  # If a callable object is provided directly, its `call` method is invoked for
+  # every function execution. Note that this means it may be called multiple
+  # times concurrently in separate threads.
+  #
+  # Alternately, the implementation may be provided as a class that should be
+  # instantiated to produce a callable object. If a class is provided, it should
+  # either subclass {FunctionsFramework::Function::CallBase} or respond to the
+  # same constructor interface, i.e. accepting arbitrary keyword arguments. A
+  # separate callable object will be instantiated from this class for every
+  # function invocation, so each instance will be used for only one invocation.
+  #
+  # Finally, an implementation can be provided as a block. If a block is
+  # provided, it will be recast as a `call` method in an anonymous subclass of
+  # {FunctionsFramework::Function::CallBase}. Thus, providing a block is really
+  # just syntactic sugar for providing a class. (This means, for example, that
+  # the `return` keyword will work within the block because it is treated as a
+  # method.)
   #
   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
+    # @param type [Symbol] The type of function. Valid types are `:http` and
+    #     `:cloud_event`.
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
     #
-    def initialize name, type, &block
+    def initialize name, type, callable = nil, &block
       @name = name
       @type = type
-      @execution_context_class = Class.new do
-        define_method :call, &block
+      @callable = @callable_class = nil
+      if callable.respond_to? :call
+        @callable = callable
+      elsif callable.is_a? ::Class
+        @callable_class = callable
+      elsif block_given?
+        @callable_class = ::Class.new CallBase do
+          define_method :call, &block
+        end
+      else
+        raise ::ArgumentError, "No callable given for function"
       end
     end
 
@@ -46,26 +82,48 @@ module FunctionsFramework
     attr_reader :type
 
     ##
-    # Call the function. You must pass an argument appropriate to the type
-    # of function.
+    # Get a callable for performing a function invocation. This will either
+    # return the singleton callable object, or instantiate a new callable from
+    # the configured class.
     #
-    #  *  A `:http` type function takes a `Rack::Request` argument, and returns
-    #     a Rack response type. See {FunctionsFramework::Registry.add_http}.
-    #  *  A `:cloud_event` type function takes a
-    #     {FunctionsFramework::CloudEvents::Event} argument, and does not
-    #     return a value. See {FunctionsFramework::Registry.add_cloud_event}.
+    # @param logger [::Logger] The logger for use by function executions. This
+    #     may or may not be used by the callable.
+    # @return [#call]
     #
-    # @param argument [Rack::Request,FunctionsFramework::CloudEvents::Event]
-    # @return [Object]
+    def new_call logger: nil
+      return @callable unless @callable.nil?
+      logger ||= FunctionsFramework.logger
+      @callable_class.new logger: logger, function_name: name, function_type: type
+    end
+
+    ##
+    # A base class for a callable object that provides calling context.
     #
-    def call argument
-      execution_context = @execution_context_class.new
-      case type
-      when :event
-        execution_context.call argument.data, argument
-      else
-        execution_context.call argument
+    # An object of this class is `self` while a function block is running.
+    #
+    class CallBase
+      ##
+      # Create a callable object with the given context.
+      #
+      # @param context [keywords] A set of context arguments. See {#context} for
+      #     a list of keys that will generally be passed in. However,
+      #     implementations should be prepared to accept any abritrary keys.
+      #
+      def initialize **context
+        @context = context
       end
+
+      ##
+      # A keyed hash of context information. Common context keys include:
+      #
+      #  *  **:logger** (`Logger`) A logger for use by this function call.
+      #  *  **:function_name** (`String`) The name of the running function.
+      #  *  **:function_type** (`Symbol`) The type of the running function,
+      #     either `:http` or `:cloud_event`.
+      #
+      # @return [Hash]
+      #
+      attr_reader :context
     end
   end
 end

data/lib/functions_framework/legacy_event_converter.rb

@@ -29,7 +29,7 @@ module FunctionsFramework
     #
     def decode_rack_env env
       content_type = CloudEvents::ContentType.new env["CONTENT_TYPE"]
-      return nil unless content_type.media_type == "application" && content_type.subtype_prefix == "json"
+      return nil unless content_type.media_type == "application" && content_type.subtype_base == "json"
       input = read_input_json env["rack.input"], content_type.charset
       return nil unless input
       raw_context = input["context"] || input

data/lib/functions_framework/registry.rb

@@ -75,21 +75,6 @@ module FunctionsFramework
       self
     end
 
-    ##
-    # This is an obsolete interface that defines an event function taking two
-    # arguments (data and context) rather than one.
-    #
-    # @deprecated Use {Registry#add_cloud_event} instead.
-    #
-    def add_event name, &block
-      name = name.to_s
-      synchronize do
-        raise ::ArgumentError, "Function already defined: #{name}" if @functions.key? name
-        @functions[name] = Function.new name, :event, &block
-      end
-      self
-    end
-
     ##
     # Add a CloudEvent function to the registry.
     #

data/lib/functions_framework/server.rb

@@ -47,7 +47,7 @@ module FunctionsFramework
         case function.type
         when :http
           HttpApp.new function, @config
-        when :event, :cloud_event
+        when :cloud_event
           EventApp.new function, @config
         else
           raise "Unrecognized function type: #{function.type}"
@@ -384,10 +384,11 @@ module FunctionsFramework
         return notfound_response if excluded_path? env
         response =
           begin
-            logger = env["rack.logger"] = @config.logger
+            logger = env["rack.logger"] ||= @config.logger
             request = ::Rack::Request.new env
             logger.info "FunctionsFramework: Handling HTTP #{request.request_method} request"
-            @function.call request
+            calling_context = @function.new_call logger: logger
+            calling_context.call request
           rescue ::StandardError => e
             e
           end
@@ -406,7 +407,7 @@ module FunctionsFramework
 
       def call env
         return notfound_response if excluded_path? env
-        logger = env["rack.logger"] = @config.logger
+        logger = env["rack.logger"] ||= @config.logger
         event = decode_event env
         response =
           case event
@@ -434,7 +435,8 @@ module FunctionsFramework
 
       def handle_cloud_event event, logger
         logger.info "FunctionsFramework: Handling CloudEvent"
-        @function.call event
+        calling_context = @function.new_call logger: logger
+        calling_context.call event
         "ok"
       rescue ::StandardError => e
         e

data/lib/functions_framework/testing.rb

@@ -87,7 +87,7 @@ module FunctionsFramework
       function = ::FunctionsFramework.global_registry[name]
       case function&.type
       when :http
-        Testing.interpret_response { function.call request }
+        Testing.interpret_response { function.new_call.call request }
       when nil
         raise "Unknown function name #{name}"
       else
@@ -97,7 +97,7 @@ module FunctionsFramework
 
     ##
     # Call the given event function for testing. The underlying function must
-    # be of type `:event` or `:cloud_event`.
+    # be of type :cloud_event`.
     #
     # @param name [String] The name of the function to call
     # @param event [FunctionsFramework::CloudEvets::Event] The event to send
@@ -106,8 +106,8 @@ module FunctionsFramework
     def call_event name, event
       function = ::FunctionsFramework.global_registry[name]
       case function&.type
-      when :event, :cloud_event
-        function.call event
+      when :cloud_event
+        function.new_call.call event
         nil
       when nil
         raise "Unknown function name #{name}"

data/lib/functions_framework/version.rb

@@ -17,5 +17,5 @@ module FunctionsFramework
   # Version of the Ruby Functions Framework
   # @return [String]
   #
-  VERSION = "0.3.1".freeze
+  VERSION = "0.4.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-27 00:00:00.000000000 Z
+date: 2020-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puma
@@ -162,6 +162,8 @@ files:
 - lib/functions_framework/cloud_events/content_type.rb
 - lib/functions_framework/cloud_events/errors.rb
 - lib/functions_framework/cloud_events/event.rb
+- lib/functions_framework/cloud_events/event/field_interpreter.rb
+- lib/functions_framework/cloud_events/event/v0.rb
 - lib/functions_framework/cloud_events/event/v1.rb
 - lib/functions_framework/cloud_events/http_binding.rb
 - lib/functions_framework/cloud_events/json_format.rb