functions_framework 0.2.0 → 0.4.1

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,21 +16,59 @@ 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
-      @block = 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
 
     ##
@@ -44,30 +82,48 @@ module FunctionsFramework
     attr_reader :type
 
     ##
-    # @return [Proc] The function code as a proc
+    # 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.
     #
-    attr_reader :block
+    # @param logger [::Logger] The logger for use by function executions. This
+    #     may or may not be used by the callable.
+    # @return [#call]
+    #
+    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
 
     ##
-    # 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 `:cloud_event` type function takes a
-    #     {FunctionsFramework::CloudEvents::Event} argument, and does not
-    #     return a value. See {FunctionsFramework::Registry.add_cloud_event}.
+    # A base class for a callable object that provides calling context.
     #
-    # @param argument [Rack::Request,FunctionsFramework::CloudEvents::Event]
-    # @return [Object]
+    # An object of this class is `self` while a function block is running.
     #
-    def call argument
-      case type
-      when :event
-        block.call argument.data, argument
-      else
-        block.call argument
+    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,13 +29,12 @@ 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
-      context = normalized_context raw_context
+      context = normalized_context input
       return nil unless context
-      construct_cloud_event context, input["data"]
+      construct_cloud_event context, input["data"], content_type.charset
     end
 
     private
@@ -50,27 +49,27 @@ module FunctionsFramework
       nil
     end
 
-    def normalized_context raw_context
-      id = raw_context["eventId"]
-      return nil unless id
-      timestamp = raw_context["timestamp"]
-      return nil unless timestamp
-      type = raw_context["eventType"]
-      return nil unless type
-      service, resource = analyze_resource raw_context["resource"], type
-      return nil unless service && resource
+    def normalized_context input
+      raw_context = input["context"]
+      id = raw_context&.[]("eventId") || input["eventId"]
+      timestamp = raw_context&.[]("timestamp") || input["timestamp"]
+      type = raw_context&.[]("eventType") || input["eventType"]
+      service, resource = analyze_resource raw_context&.[]("resource") || input["resource"]
+      service ||= service_from_type type
+      return nil unless id && timestamp && type && service && resource
       { id: id, timestamp: timestamp, type: type, service: service, resource: resource }
     end
 
-    def analyze_resource raw_resource, type
+    def analyze_resource raw_resource
+      service = resource = nil
       case raw_resource
       when ::Hash
-        [raw_resource["service"], raw_resource["name"]]
+        service = raw_resource["service"]
+        resource = raw_resource["name"]
       when ::String
-        [service_from_type(type), raw_resource]
-      else
-        [nil, nil]
+        resource = raw_resource
       end
+      [service, resource]
     end
 
     def service_from_type type
@@ -80,16 +79,18 @@ module FunctionsFramework
       nil
     end
 
-    def construct_cloud_event context, data
+    def construct_cloud_event context, data, charset
       source, subject = convert_source context[:service], context[:resource]
       type = LEGACY_TYPE_TO_CE_TYPE[context[:type]]
       return nil unless type && source
+      ce_data = convert_data context[:service], data
+      content_type = "application/json; charset=#{charset}"
       CloudEvents::Event.new id:                context[:id],
                              source:            source,
                              type:              type,
                              spec_version:      "1.0",
-                             data_content_type: "application/json",
-                             data:              data,
+                             data_content_type: content_type,
+                             data:              ce_data,
                              subject:           subject,
                              time:              context[:timestamp]
     end
@@ -104,6 +105,14 @@ module FunctionsFramework
       end
     end
 
+    def convert_data service, data
+      if service == "pubsub.googleapis.com"
+        { "message" => data, "subscription" => nil }
+      else
+        data
+      end
+    end
+
     LEGACY_TYPE_TO_SERVICE = {
       %r{^providers/cloud\.firestore/} => "firestore.googleapis.com",
       %r{^providers/cloud\.pubsub/}    => "pubsub.googleapis.com",

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}"
@@ -149,8 +149,12 @@ module FunctionsFramework
         ::Signal.trap "SIGINT" do
           Server.signal_enqueue "SIGINT", @config.logger, @server
         end
-        ::Signal.trap "SIGHUP" do
-          Server.signal_enqueue "SIGHUP", @config.logger, @server
+        begin
+          ::Signal.trap "SIGHUP" do
+            Server.signal_enqueue "SIGHUP", @config.logger, @server
+          end
+        rescue ::ArgumentError # rubocop:disable Lint/HandleExceptions
+          # Not available on all systems
         end
         @signals_installed = true
       end
@@ -384,10 +388,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 +411,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 +439,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