functions_framework 0.5.1 → 0.8.0

data/lib/functions_framework.rb

@@ -71,7 +71,7 @@ require "functions_framework/version"
 #
 module FunctionsFramework
   @global_registry = Registry.new
-  @logger = ::Logger.new ::STDERR
+  @logger = ::Logger.new $stderr
   @logger.level = ::Logger::INFO
 
   ##
@@ -166,8 +166,30 @@ 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.
+    # Define a server startup task. This is useful for initializing shared
+    # resources that should be accessible across all function invocations in
+    # this Ruby VM.
+    #
+    # Startup tasks are run just before a server starts. All startup tasks are
+    # guaranteed to complete before any function executes. However, they are
+    # 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 the {FunctionsFramework::Function} identifying
+    # the function to execute, and have no return value.
+    #
+    # @param block [Proc] The startup task
+    # @return [self]
+    #
+    def on_startup &block
+      global_registry.add_startup_task(&block)
+      self
+    end
+
+    ##
+    # 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.
@@ -183,7 +205,12 @@ module FunctionsFramework
         function = global_registry[target]
         raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
       end
-      server = Server.new function, &block
+      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

@@ -42,8 +42,31 @@ module FunctionsFramework
       @detailed_errors = nil
       @signature_type = ::ENV["FUNCTION_SIGNATURE_TYPE"]
       @logging_level = init_logging_level
+      @what_to_do = nil
+      @error_message = nil
+      @exit_code = 0
     end
 
+    ##
+    # Determine if an error has occurred
+    #
+    # @return [boolean]
+    #
+    def error?
+      !@error_message.nil?
+    end
+
+    ##
+    # @return [Integer] The current exit status.
+    #
+    attr_reader :exit_code
+
+    ##
+    # @return [String] The current error message.
+    # @return [nil] if no error has occurred.
+    #
+    attr_reader :error_message
+
     ##
     # Parse the given command line arguments.
     # Exits if argument parsing failed.
@@ -51,8 +74,8 @@ module FunctionsFramework
     # @param argv [Array<String>]
     # @return [self]
     #
-    def parse_args argv # rubocop:disable Metrics/MethodLength
-      option_parser = ::OptionParser.new do |op| # rubocop:disable Metrics/BlockLength
+    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|
           @target = val
@@ -84,55 +107,92 @@ module FunctionsFramework
         op.on "--[no-]detailed-errors", "Set whether to show error details" do |val|
           @detailed_errors = val
         end
+        op.on "--verify", "Verify the app only, but do not run the server." do
+          @what_to_do ||= :verify
+        end
         op.on "-v", "--verbose", "Increase log verbosity" do
           @logging_level -= 1
         end
         op.on "-q", "--quiet", "Decrease log verbosity" do
           @logging_level += 1
         end
+        op.on "--version", "Display the framework version" do
+          @what_to_do ||= :version
+        end
         op.on "--help", "Display help" do
-          puts op
-          exit
+          @what_to_do ||= :help
         end
       end
-      option_parser.parse! argv
-      error "Unrecognized arguments: #{argv}\n#{op}" unless argv.empty?
+      begin
+        @option_parser.parse! argv
+        error! "Unrecognized arguments: #{argv}\n#{@option_parser}", 2 unless argv.empty?
+      rescue ::OptionParser::ParseError => e
+        error! "#{e.message}\n#{@option_parser}", 2
+      end
       self
     end
 
     ##
-    # Run the configured server, and block until it stops.
-    # If a validation error occurs, print a message and exit.
+    # Perform the requested function.
+    #
+    #  *  If the `--version` flag was given, display the version.
+    #  *  If the `--help` flag was given, display online help.
+    #  *  If the `--verify` flag was given, load and verify the function,
+    #     displaying any errors, then exit without starting a server.
+    #  *  Otherwise, start the configured server and block until it stops.
     #
     # @return [self]
     #
     def run
-      begin
-        server = start_server
-      rescue ::StandardError => e
-        error e.message
+      return self if error?
+      case @what_to_do
+      when :version
+        puts ::FunctionsFramework::VERSION
+      when :help
+        puts @option_parser
+      when :verify
+        begin
+          load_function
+          puts "OK"
+        rescue ::StandardError => e
+          error! e.message
+        end
+      else
+        begin
+          start_server.wait_until_stopped
+        rescue ::StandardError => e
+          error! e.message
+        end
       end
-      server.wait_until_stopped
       self
     end
 
     ##
-    # Start the configured server and return the running server object.
+    # Finish the CLI, displaying any error status and exiting with the current
+    # exit code. Never returns.
+    #
+    def complete
+      warn @error_message if @error_message
+      exit @exit_code
+    end
+
+    ##
+    # Load the source and get and verify the requested function.
     # If a validation error occurs, raise an exception.
-    # This is used for testing the CLI.
     #
-    # @return [FunctionsFramework::Server]
+    # @return [FunctionsFramework::Function]
     #
     # @private
     #
-    def start_server
+    def load_function
       ::FunctionsFramework.logger.level = @logging_level
-      ::FunctionsFramework.logger.info "FunctionsFramework v#{VERSION} server starting."
+      ::FunctionsFramework.logger.info "FunctionsFramework v#{VERSION}"
       ::ENV["FUNCTION_TARGET"] = @target
       ::ENV["FUNCTION_SOURCE"] = @source
       ::ENV["FUNCTION_SIGNATURE_TYPE"] = @signature_type
       ::FunctionsFramework.logger.info "FunctionsFramework: Loading functions from #{@source.inspect}..."
       load @source
+      ::FunctionsFramework.logger.info "FunctionsFramework: Looking for function name #{@target.inspect}..."
       function = ::FunctionsFramework.global_registry[@target]
       raise "Undefined function: #{@target.inspect}" if function.nil?
       unless @signature_type.nil? ||
@@ -140,6 +200,20 @@ module FunctionsFramework
              ["cloudevent", "event"].include?(@signature_type) && function.type == :cloud_event
         raise "Function #{@target.inspect} does not match type #{@signature_type}"
       end
+      function
+    end
+
+    ##
+    # Start the configured server and return the running server object.
+    # If a validation error occurs, raise an exception.
+    #
+    # @return [FunctionsFramework::Server]
+    #
+    # @private
+    #
+    def start_server
+      function = load_function
+      ::FunctionsFramework.logger.info "FunctionsFramework: Starting server..."
       ::FunctionsFramework.start function do |config|
         config.rack_env = @env
         config.port = @port
@@ -160,12 +234,13 @@ module FunctionsFramework
     end
 
     ##
-    # Print the given error message and exit.
-    # @param message [String]
+    # Set the error status.
+    # @param message [String] Error message.
+    # @param code [Integer] Exit code, defaults to 1.
     #
-    def error message
-      warn message
-      exit 1
+    def error! message, code = 1
+      @error_message = message
+      @exit_code = code
     end
   end
 end

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 value.is_a? LazyGlobal
+        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