functions_framework 0.1.1 → 0.4.0

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,32 +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 `: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.
+    # 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

@@ -0,0 +1,145 @@
+# 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 "json"
+
+module FunctionsFramework
+  ##
+  # Converter from legacy GCF event formats to CloudEvents.
+  #
+  class LegacyEventConverter
+    ##
+    # Decode an event from the given Rack environment hash.
+    #
+    # @param env [Hash] The Rack environment
+    # @return [FunctionsFramework::CloudEvents::Event] if the request could
+    #     be converted
+    # @return [nil] if the event format was not recognized.
+    #
+    def decode_rack_env env
+      content_type = CloudEvents::ContentType.new env["CONTENT_TYPE"]
+      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
+      return nil unless context
+      construct_cloud_event context, input["data"]
+    end
+
+    private
+
+    def read_input_json input, charset
+      input = input.read if input.respond_to? :read
+      input = input.encode charset if charset
+      content = ::JSON.parse input
+      content = nil unless content.is_a? ::Hash
+      content
+    rescue ::JSON::ParserError
+      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
+      { id: id, timestamp: timestamp, type: type, service: service, resource: resource }
+    end
+
+    def analyze_resource raw_resource, type
+      case raw_resource
+      when ::Hash
+        [raw_resource["service"], raw_resource["name"]]
+      when ::String
+        [service_from_type(type), raw_resource]
+      else
+        [nil, nil]
+      end
+    end
+
+    def service_from_type type
+      LEGACY_TYPE_TO_SERVICE.each do |pattern, service|
+        return service if pattern =~ type
+      end
+      nil
+    end
+
+    def construct_cloud_event context, data
+      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
+      CloudEvents::Event.new id:                context[:id],
+                             source:            source,
+                             type:              type,
+                             spec_version:      "1.0",
+                             data_content_type: "application/json",
+                             data:              ce_data,
+                             subject:           subject,
+                             time:              context[:timestamp]
+    end
+
+    def convert_source service, resource
+      if service == "storage.googleapis.com"
+        match = %r{^(projects/[^/]+/buckets/[^/]+)/([^#]+)(?:#.*)?$}.match resource
+        return [nil, nil] unless match
+        ["//#{service}/#{match[1]}", match[2]]
+      else
+        ["//#{service}/#{resource}", nil]
+      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",
+      %r{^providers/cloud\.storage/}   => "storage.googleapis.com",
+      %r{^providers/firebase\.auth/}   => "firebase.googleapis.com",
+      %r{^providers/google\.firebase}  => "firebase.googleapis.com"
+    }.freeze
+
+    LEGACY_TYPE_TO_CE_TYPE = {
+      "google.pubsub.topic.publish"                              => "google.cloud.pubsub.topic.v1.messagePublished",
+      "providers/cloud.pubsub/eventTypes/topic.publish"          => "google.cloud.pubsub.topic.v1.messagePublished",
+      "google.storage.object.finalize"                           => "google.cloud.storage.object.v1.finalized",
+      "google.storage.object.delete"                             => "google.cloud.storage.object.v1.deleted",
+      "google.storage.object.archive"                            => "google.cloud.storage.object.v1.archived",
+      "google.storage.object.metadataUpdate"                     => "google.cloud.storage.object.v1.metadataUpdated",
+      "providers/cloud.firestore/eventTypes/document.write"      => "google.cloud.firestore.document.v1.written",
+      "providers/cloud.firestore/eventTypes/document.create"     => "google.cloud.firestore.document.v1.created",
+      "providers/cloud.firestore/eventTypes/document.update"     => "google.cloud.firestore.document.v1.updated",
+      "providers/cloud.firestore/eventTypes/document.delete"     => "google.cloud.firestore.document.v1.deleted",
+      "providers/firebase.auth/eventTypes/user.create"           => "google.firebase.auth.user.v1.created",
+      "providers/firebase.auth/eventTypes/user.delete"           => "google.firebase.auth.user.v1.deleted",
+      "providers/google.firebase.analytics/eventTypes/event.log" => "google.firebase.analytics.log.v1.written",
+      "providers/google.firebase.database/eventTypes/ref.create" => "google.firebase.database.document.v1.created",
+      "providers/google.firebase.database/eventTypes/ref.write"  => "google.firebase.database.document.v1.written",
+      "providers/google.firebase.database/eventTypes/ref.update" => "google.firebase.database.document.v1.updated",
+      "providers/google.firebase.database/eventTypes/ref.delete" => "google.firebase.database.document.v1.deleted",
+      "providers/cloud.storage/eventTypes/object.change"         => "google.cloud.storage.object.v1.finalized"
+    }.freeze
+  end
+end

data/lib/functions_framework/registry.rb

@@ -75,42 +75,6 @@ module FunctionsFramework
       self
     end
 
-    ##
-    # Add a CloudEvent function to the registry.
-    #
-    # You must provide a name for the function, and a block that implemets the
-    # function. The block should take two arguments: the event _data_ and the
-    # event _context_. Any return value is ignored.
-    #
-    # The event data argument will be one of the following types:
-    #  *  A `String` (with encoding `ASCII-8BIT`) if the data is in the form of
-    #     binary data. You may choose to perform additional interpretation of
-    #     the binary data using information in the content type provided by the
-    #     context argument.
-    #  *  Any data type that can be represented in JSON (i.e. `String`,
-    #     `Integer`, `Array`, `Hash`, `true`, `false`, or `nil`) if the event
-    #     came with a JSON payload. The content type may also be set in the
-    #     context if the data is a String.
-    #
-    # The context argument will be of type {FunctionsFramework::CloudEvents::Event},
-    # and will contain CloudEvents context attributes such as `id` and `type`.
-    #
-    # See also {#add_cloud_event} which creates a function that takes a single
-    # argument of type {FunctionsFramework::CloudEvents::Event}.
-    #
-    # @param name [String] The function name
-    # @param block [Proc] The function code as a proc
-    # @return [self]
-    #
-    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.
     #
@@ -118,9 +82,6 @@ module FunctionsFramework
     # function. The block should take _one_ argument: the event object of type
     # {FunctionsFramework::CloudEvents::Event}. Any return value is ignored.
     #
-    # See also {#add_event} which creates a function that takes data and
-    # context as separate arguments.
-    #
     # @param name [String] The function name
     # @param block [Proc] The function code as a proc
     # @return [self]

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}"
@@ -212,7 +212,7 @@ module FunctionsFramework
       # @param bind_addr [String,nil]
       #
       def bind_addr= bind_addr
-        @bind_addr = bind_addr || ::ENV["BIND_ADDR"] || "0.0.0.0"
+        @bind_addr = bind_addr || ::ENV["FUNCTION_BIND_ADDR"] || "0.0.0.0"
       end
 
       ##
@@ -228,7 +228,7 @@ module FunctionsFramework
       # @param min_threads [Integer,nil]
       #
       def min_threads= min_threads
-        @min_threads = (min_threads || ::ENV["MIN_THREADS"])&.to_i
+        @min_threads = (min_threads || ::ENV["FUNCTION_MIN_THREADS"])&.to_i
       end
 
       ##
@@ -236,7 +236,7 @@ module FunctionsFramework
       # @param max_threads [Integer,nil]
       #
       def max_threads= max_threads
-        @max_threads = (max_threads || ::ENV["MAX_THREADS"])&.to_i
+        @max_threads = (max_threads || ::ENV["FUNCTION_MAX_THREADS"])&.to_i
       end
 
       ##
@@ -244,8 +244,12 @@ module FunctionsFramework
       # @param show_error_details [Boolean,nil]
       #
       def show_error_details= show_error_details
-        val = show_error_details.nil? ? ::ENV["DETAILED_ERRORS"] : show_error_details
-        @show_error_details = val ? true : false
+        @show_error_details =
+          if show_error_details.nil?
+            !::ENV["FUNCTION_DETAILED_ERRORS"].to_s.empty?
+          else
+            show_error_details ? true : false
+          end
       end
 
       ##
@@ -315,15 +319,15 @@ module FunctionsFramework
 
     ## @private
     class AppBase
-      BLACKLISTED_PATHS = ["/favicon.ico", "/robots.txt"].freeze
+      EXCLUDED_PATHS = ["/favicon.ico", "/robots.txt"].freeze
 
       def initialize config
         @config = config
       end
 
-      def blacklisted_path? env
+      def excluded_path? env
         path = env[::Rack::SCRIPT_NAME].to_s + env[::Rack::PATH_INFO].to_s
-        BLACKLISTED_PATHS.include? path
+        EXCLUDED_PATHS.include? path
       end
 
       def interpret_response response
@@ -335,15 +339,13 @@ module FunctionsFramework
         when ::String
           string_response response, "text/plain", 200
         when ::Hash
-          json = ::JSON.dump response
-          string_response json, "application/json", 200
+          string_response ::JSON.dump(response), "application/json", 200
+        when CloudEvents::CloudEventsError
+          cloud_events_error_response response
         when ::StandardError
-          error = error_message response
-          string_response error, "text/plain", 500
+          error_response "#{response.class}: #{response.message}\n#{response.backtrace}\n"
         else
-          e = ::StandardError.new "Unexpected response type: #{response.class}"
-          error = error_message e
-          string_response error, "text/plain", 500
+          error_response "Unexpected response type: #{response.class}"
         end
       end
 
@@ -359,20 +361,15 @@ module FunctionsFramework
         [status, headers, [string]]
       end
 
-      def error_message error
-        if @config.show_error_details?
-          "#{error.class}: #{error.message}\n#{error.backtrace}\n"
-        else
-          "Unexpected internal error"
-        end
+      def cloud_events_error_response error
+        @config.logger.warn error
+        string_response "#{error.class}: #{error.message}", "text/plain", 400
       end
 
-      def usage_message error
-        if @config.show_error_details?
-          "Failed to decode CloudEvent: #{error.inspect}"
-        else
-          "Failed to decode CloudEvent"
-        end
+      def error_response message
+        @config.logger.error message
+        message = "Unexpected internal error" unless @config.show_error_details?
+        string_response message, "text/plain", 500
       end
     end
 
@@ -384,15 +381,15 @@ module FunctionsFramework
       end
 
       def call env
-        return notfound_response if blacklisted_path? env
+        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
-            logger.warn e
             e
           end
         interpret_response response
@@ -404,33 +401,46 @@ module FunctionsFramework
       def initialize function, config
         super config
         @function = function
+        @cloud_events = CloudEvents::HttpBinding.default
+        @legacy_events = LegacyEventConverter.new
       end
 
       def call env
-        return notfound_response if blacklisted_path? env
-        logger = env["rack.logger"] = @config.logger
-        event =
-          begin
-            CloudEvents.decode_rack_env env
-          rescue ::StandardError => e
-            e
-          end
+        return notfound_response if excluded_path? env
+        logger = env["rack.logger"] ||= @config.logger
+        event = decode_event env
         response =
-          if event.is_a? CloudEvents::Event
-            logger.info "FunctionsFramework: Handling CloudEvent"
-            begin
-              @function.call event
-              "ok"
-            rescue ::StandardError => e
-              logger.warn e
-              e
-            end
+          case event
+          when CloudEvents::Event
+            handle_cloud_event event, logger
+          when ::Array
+            CloudEvents::HttpContentError.new "Batched CloudEvents are not supported"
+          when CloudEvents::CloudEventsError
+            event
           else
-            logger.warn e.inspect
-            string_response usage_message(e), "text/plain", 400
+            raise "Unexpected event type: #{event.class}"
           end
         interpret_response response
       end
+
+      private
+
+      def decode_event env
+        @cloud_events.decode_rack_env(env) ||
+          @legacy_events.decode_rack_env(env) ||
+          raise(CloudEvents::HttpContentError, "Unrecognized event format")
+      rescue CloudEvents::CloudEventsError => e
+        e
+      end
+
+      def handle_cloud_event event, logger
+        logger.info "FunctionsFramework: Handling CloudEvent"
+        calling_context = @function.new_call logger: logger
+        calling_context.call event
+        "ok"
+      rescue ::StandardError => e
+        e
+      end
     end
   end
 end