functions_framework 0.6.0 → 0.10.0

data/lib/functions_framework.rb

@@ -175,10 +175,8 @@ module FunctionsFramework
     # run only when preparing to run functions. They are not run, for example,
     # if an app is loaded to verify its integrity during deployment.
     #
-    # Startup tasks are passed two arguments: the {FunctionsFramework::Function}
-    # identifying the function to execute, and the
-    # {FunctionsFramework::Server::Config} specifying the (frozen) server
-    # configuration. Tasks have no return value.
+    # Startup tasks are passed the {FunctionsFramework::Function} identifying
+    # the function to execute, and have no return value.
     #
     # @param block [Proc] The startup task
     # @return [self]
@@ -189,8 +187,9 @@ module FunctionsFramework
     end
 
     ##
-    # Start the functions framework server in the background. The server will
-    # look up the given target function name in the global registry.
+    # Run startup tasks, then start the functions framework server in the
+    # background. The startup tasks and target function will be looked up in
+    # the global registry.
     #
     # @param target [FunctionsFramework::Function,String] The function to run,
     #     or the name of the function to look up in the global registry.
@@ -206,8 +205,12 @@ module FunctionsFramework
         function = global_registry[target]
         raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
       end
-      server = Server.new function, &block
-      global_registry.run_startup_tasks server
+      globals = function.populate_globals
+      server = Server.new function, globals, &block
+      global_registry.startup_tasks.each do |task|
+        task.call function, globals: globals, logger: server.config.logger
+      end
+      globals.freeze
       server.respond_to_signals
       server.start
     end

data/lib/functions_framework/cli.rb

@@ -74,7 +74,7 @@ module FunctionsFramework
     # @param argv [Array<String>]
     # @return [self]
     #
-    def parse_args argv # rubocop:disable Metrics/MethodLength
+    def parse_args argv # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
       @option_parser = ::OptionParser.new do |op| # rubocop:disable Metrics/BlockLength
         op.on "-t", "--target TARGET",
               "Set the name of the function to execute (defaults to #{DEFAULT_TARGET})" do |val|

data/lib/functions_framework/function.rb

@@ -18,44 +18,91 @@ module FunctionsFramework
   #
   # A function has a name, a type, and an implementation.
   #
+  # ## Function implementations
+  #
   # 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
-  # [CloudEvent](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event)
-  # argument, and does not return a value.
-  # See {FunctionsFramework::Registry.add_cloud_event}.
+  # 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
+  #     [CloudEvent](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event)
+  #     argument, and does not return a value. See
+  #     {FunctionsFramework::Registry.add_cloud_event}.
+  #  *  For a function of type `:startup_task`, the `call` method takes a
+  #     single {FunctionsFramework::Function} argument, and does not return a
+  #     value. See {FunctionsFramework::Registry.add_startup_task}.
   #
-  # 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.
+  # The implementation can be specified in one of three ways:
   #
-  # 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.
+  #  *  A callable object can be passed in the `callable` keyword argument. The
+  #     object's `call` method will be invoked for every function execution.
+  #     Note that this means it may be called multiple times concurrently in
+  #     separate threads.
+  #  *  A callable _class_ can be passed in the `callable` keyword argument.
+  #     This class should subclass {FunctionsFramework::Function::Callable} and
+  #     define the `call` method. A separate instance of this class will be
+  #     created for each function invocation.
+  #  *  A block can be provided. It will be used to define the `call` method in
+  #     an anonymous subclass of {FunctionsFramework::Function::Callable}.
+  #     Thus, providing a block is really just syntactic sugar for providing a
+  #     class. (This means, for example, that the `return` keyword will work
+  #     as expected within the block because it is treated as a method.)
   #
-  # 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.)
+  # When the implementation is provided as a callable class or block, it is
+  # executed in the context of a {FunctionsFramework::Function::Callable}
+  # object. This object provides a convenience accessor for the Logger, and
+  # access to _globals_, which are data defined by the application startup
+  # process and available to each function invocation. Typically, globals are
+  # used for shared global resources such as service connections and clients.
   #
   class Function
+    ##
+    # Create a new HTTP function definition.
+    #
+    # @param name [String] The function name
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    def self.http name, callable: nil, &block
+      new name, :http, callable: callable, &block
+    end
+
+    ##
+    # Create a new CloudEvents function definition.
+    #
+    # @param name [String] The function name
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    def self.cloud_event name, callable: nil, &block
+      new name, :cloud_event, callable: callable, &block
+    end
+
+    ##
+    # Create a new startup task function definition.
+    #
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    def self.startup_task callable: nil, &block
+      new nil, :startup_task, callable: callable, &block
+    end
+
     ##
     # Create a new function definition.
     #
     # @param name [String] The function name
-    # @param type [Symbol] The type of function. Valid types are `:http` and
-    #     `:cloud_event`.
+    # @param type [Symbol] The type of function. Valid types are `:http`,
+    #     `:cloud_event`, and `:startup_task`.
     # @param callable [Class,#call] A callable object or class.
     # @param block [Proc] The function code as a block.
     #
-    def initialize name, type, callable = nil, &block
+    def initialize name, type, callable: nil, &block
       @name = name
       @type = type
       @callable = @callable_class = nil
@@ -64,7 +111,7 @@ module FunctionsFramework
       elsif callable.is_a? ::Class
         @callable_class = callable
       elsif block_given?
-        @callable_class = ::Class.new CallBase do
+        @callable_class = ::Class.new Callable do
           define_method :call, &block
         end
       else
@@ -83,18 +130,60 @@ module FunctionsFramework
     attr_reader :type
 
     ##
-    # 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.
-    #
-    # @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
+    # Populate the given globals hash with this function's info.
+    #
+    # @param globals [Hash] Initial globals hash (optional).
+    # @return [Hash] A new globals hash with this function's info included.
+    #
+    def populate_globals globals = nil
+      result = { function_name: name, function_type: type }
+      result.merge! globals if globals
+      result
+    end
+
+    ##
+    # Call the function given a set of arguments. Set the given logger and/or
+    # globals in the context if the callable supports it.
+    #
+    # If the given arguments exceeds what the function will accept, the args
+    # are silently truncated. However, if the function requires more arguments
+    # than are provided, an ArgumentError is raised.
+    #
+    # @param args [Array] Argument to pass to the function.
+    # @param logger [Logger] Logger for use by function executions.
+    # @param globals [Hash] Globals for the function execution context
+    # @return [Object] The function return value.
+    #
+    def call *args, globals: nil, logger: nil
+      callable = @callable || @callable_class.new(globals: globals, logger: logger)
+      params = callable.method(:call).parameters.map(&:first)
+      unless params.include? :rest
+        max_params = params.count(:req) + params.count(:opt)
+        args = args.take max_params
+      end
+      callable.call(*args)
+    end
+
+    ##
+    # A lazy evaluator for a global
+    # @private
+    #
+    class LazyGlobal
+      def initialize block
+        @block = block
+        @value = nil
+        @mutex = ::Mutex.new
+      end
+
+      def value
+        @mutex.synchronize do
+          if @block
+            @value = @block.call
+            @block = nil
+          end
+          @value
+        end
+      end
     end
 
     ##
@@ -102,29 +191,82 @@ module FunctionsFramework
     #
     # An object of this class is `self` while a function block is running.
     #
-    class CallBase
+    class Callable
       ##
       # 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.
+      # @param globals [Hash] A set of globals available to the call.
+      # @param logger [Logger] A logger for use by the function call.
       #
-      def initialize **context
-        @context = context
+      def initialize globals: nil, logger: nil
+        @__globals = globals || {}
+        @__logger = logger || FunctionsFramework.logger
       end
 
       ##
-      # A keyed hash of context information. Common context keys include:
+      # Get the given named global.
+      #
+      # For most function calls, the following globals will be defined:
       #
-      #  *  **: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]
+      # You can also set additional globals from a startup task.
+      #
+      # @param key [Symbol,String] The name of the global to get.
+      # @return [Object]
+      #
+      def global key
+        value = @__globals[key]
+        value = value.value if LazyGlobal === value
+        value
+      end
+
+      ##
+      # Set a global. This can be called from startup tasks, but the globals
+      # are frozen when the server starts, so this call will raise an exception
+      # if called from a normal function.
+      #
+      # You can set a global to a final value, or you can provide a block that
+      # lazily computes the global the first time it is requested.
+      #
+      # @overload set_global(key, value)
+      #   Set the given global to the given value. For example:
+      #
+      #       set_global(:project_id, "my-project-id")
+      #
+      #   @param key [Symbol,String]
+      #   @param value [Object]
+      #   @return [self]
+      #
+      # @overload set_global(key, &block)
+      #   Call the given block to compute the global's value only when the
+      #   value is actually requested. This block will be called at most once,
+      #   and its result reused for subsequent calls. For example:
+      #
+      #       set_global(:connection_pool) do
+      #         ExpensiveConnectionPool.new
+      #       end
       #
-      attr_reader :context
+      #   @param key [Symbol,String]
+      #   @param block [Proc] A block that lazily computes a value
+      #   @yieldreturn [Object] The value
+      #   @return [self]
+      #
+      def set_global key, value = nil, &block
+        @__globals[key] = block ? LazyGlobal.new(block) : value
+        self
+      end
+
+      ##
+      # A logger for use by this call.
+      #
+      # @return [Logger]
+      #
+      def logger
+        @__logger
+      end
     end
   end
 end

data/lib/functions_framework/legacy_event_converter.rb

@@ -27,20 +27,21 @@ module FunctionsFramework
     # @return [nil] if the event format was not recognized.
     #
     def decode_rack_env env
-      content_type = ::CloudEvents::ContentType.new env["CONTENT_TYPE"]
+      content_type = ::CloudEvents::ContentType.new env["CONTENT_TYPE"], default_charset: "utf-8"
       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
+      input = convert_raw_pubsub_event input, env if raw_pubsub_payload? input
       context = normalized_context input
       return nil unless context
-      construct_cloud_event context, input["data"], content_type.charset
+      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
+      input.force_encoding charset if charset
       content = ::JSON.parse input
       content = nil unless content.is_a? ::Hash
       content
@@ -48,17 +49,51 @@ module FunctionsFramework
       nil
     end
 
+    def raw_pubsub_payload? input
+      return false if input.include?("context") || !input.include?("subscription")
+      message = input["message"]
+      message.is_a?(::Hash) && message.include?("data") && message.include?("messageId")
+    end
+
+    def convert_raw_pubsub_event input, env
+      message = input["message"]
+      path = "#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+      path_match = %r{projects/[^/?]+/topics/[^/?]+}.match path
+      topic = path_match ? path_match[0] : "UNKNOWN_PUBSUB_TOPIC"
+      timestamp = message["publishTime"] || ::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ")
+      {
+        "context" => {
+          "eventId" => message["messageId"],
+          "timestamp" => timestamp,
+          "eventType" => "google.pubsub.topic.publish",
+          "resource" => {
+            "service" => "pubsub.googleapis.com",
+            "type" => "type.googleapis.com/google.pubsub.v1.PubsubMessage",
+            "name" => topic
+          }
+        },
+        "data" => {
+          "@type" => "type.googleapis.com/google.pubsub.v1.PubsubMessage",
+          "data" => message["data"],
+          "attributes" => message["attributes"]
+        }
+      }
+    end
+
     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"]
+      id = normalized_context_field input, "eventId"
+      timestamp = normalized_context_field input, "timestamp"
+      type = normalized_context_field input, "eventType"
+      service, resource = analyze_resource normalized_context_field 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 normalized_context_field input, field
+      input["context"]&.[](field) || input[field]
+    end
+
     def analyze_resource raw_resource
       service = resource = nil
       case raw_resource
@@ -78,37 +113,47 @@ module FunctionsFramework
       nil
     end
 
-    def construct_cloud_event context, data, charset
+    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
-      content_type = "application/json; charset=#{charset}"
+      ce_data, data_subject = convert_data context[:service], data
+      content_type = "application/json"
       ::CloudEvents::Event.new id:                context[:id],
                                source:            source,
                                type:              type,
                                spec_version:      "1.0",
                                data_content_type: content_type,
                                data:              ce_data,
-                               subject:           subject,
+                               subject:           subject || data_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
+      return ["//#{service}/#{resource}", nil] unless CE_SERVICE_TO_RESOURCE_RE.key? service
+
+      match = CE_SERVICE_TO_RESOURCE_RE[service].match resource
+      return [nil, nil] unless match
+      ["//#{service}/#{match[1]}", match[2]]
     end
 
     def convert_data service, data
-      if service == "pubsub.googleapis.com"
-        { "message" => data, "subscription" => nil }
+      case service
+      when "pubsub.googleapis.com"
+        [{ "message" => data }, nil]
+      when "firebaseauth.googleapis.com"
+        if data.key? "metadata"
+          FIREBASE_AUTH_METADATA_LEGACY_TO_CE.each do |old_key, new_key|
+            if data["metadata"].key? old_key
+              data["metadata"][new_key] = data["metadata"][old_key]
+              data["metadata"].delete old_key
+            end
+          end
+        end
+        subject = "users/#{data['uid']}" if data.key? "uid"
+        [data, subject]
       else
-        data
+        [data, nil]
       end
     end
 
@@ -116,8 +161,9 @@ module FunctionsFramework
       %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"
+      %r{^providers/firebase\.auth/}   => "firebaseauth.googleapis.com",
+      %r{^providers/google\.firebase\.analytics/} => "firebase.googleapis.com",
+      %r{^providers/google\.firebase\.database/} => "firebasedatabase.googleapis.com"
     }.freeze
 
     LEGACY_TYPE_TO_CE_TYPE = {
@@ -140,5 +186,18 @@ module FunctionsFramework
       "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
+
+    CE_SERVICE_TO_RESOURCE_RE = {
+      "firebase.googleapis.com"         => %r{^(projects/[^/]+)/(events/[^/]+)$},
+      "firebasedatabase.googleapis.com" => %r{^(projects/_/instances/[^/]+)/(refs/.+)$},
+      "firestore.googleapis.com"        => %r{^(projects/[^/]+/databases/\(default\))/(documents/.+)$},
+      "storage.googleapis.com"          => %r{^(projects/[^/]+/buckets/[^/]+)/([^#]+)(?:#.*)?$}
+    }.freeze
+
+    # Map Firebase Auth legacy event metadata field names to their equivalent CloudEvent field names.
+    FIREBASE_AUTH_METADATA_LEGACY_TO_CE = {
+      "createdAt"      => "createTime",
+      "lastSignedInAt" => "lastSignInTime"
+    }.freeze
   end
 end