functions_framework 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e8f0eda1f51ead6ec3bd53d711d2a7816b5077351f56bfa491311c73461a02d
-  data.tar.gz: 21921bddd89a66dc95245850cb475967fd5e8de7c678bf4e154d07d7a8264290
+  metadata.gz: 67b0d5e61bb58f49adefbff9794c960438c1577b4e3d54ee5bf072b134834b71
+  data.tar.gz: 9cb295fd8ba39ea9ad5e8eab1c3055eaa18dddef5a1838cc58d7dcdb2d12fc5e
 SHA512:
-  metadata.gz: '08633f2559e4d787f23e2711d40ff17437e74cd9ee4589346bd3c4f567815c422cb6e2827125bad2de5d23f4e52c3a09162db609a4fd62aee4374144ae16686e'
-  data.tar.gz: 759e2fe6a395fe1ea53ba90bbf5026635429fbdacf161b3f87879d31753532b7ef005fbfce797c6ca599bca441f1919b4d61a508cf43877fee18090a4e8f9fec
+  metadata.gz: 99e58e1511a97dc9e8643a034bc089f5bb4b71d5f842b507151d8728f058a3763b0f55dcd952ac71f212773e6087cb333fcfebb814a33f57cd2057fde09d6272
+  data.tar.gz: e5afdebdc20c069c247e58196d75787a8c3b3e51924b7714851006ade62dc70bce62cd9e42501528103eb41f3ffc2d6239e9dd8c6650798bdbd1693268fa431a

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### v0.6.0 / 2020-09-17
+
+* ADDED: You can use the --version flag to print the framework version
+* ADDED: You can use the --verify flag to verify that a given function is defined
+* ADDED: You can now define blocks that are executed at server startup
+
 ### v0.5.2 / 2020-09-06
 
 * FIXED: Use global $stderr rather than STDERR for logger 

data/bin/functions-framework

@@ -16,4 +16,4 @@
 
 require "functions_framework/cli"
 
-::FunctionsFramework::CLI.new.parse_args(::ARGV).run
+::FunctionsFramework::CLI.new.parse_args(::ARGV).run.complete

data/bin/functions-framework-ruby

@@ -16,4 +16,4 @@
 
 require "functions_framework/cli"
 
-::FunctionsFramework::CLI.new.parse_args(::ARGV).run
+::FunctionsFramework::CLI.new.parse_args(::ARGV).run.complete

data/docs/writing-functions.md

@@ -197,6 +197,68 @@ FunctionsFramework.http "error_reporter" do |request|
 end
 ```
 
+## Shared resources
+
+Generally, functions should be self-contained and stateless, and should not use
+or share any global state in the Ruby VM. This is because serverless runtimes
+may spin up or terminate instances of your app at any time, and because a
+single instance may be running multiple functions at a time in separate threads.
+
+However, it is sometimes useful to share a resource across multiple function
+invocations that run on the same Ruby instance. For example, you might establish
+a single connection to a remote database or other service, and share it across
+function invocations to avoid incurring the overhead of re-establishing it
+for every function invocation.
+
+When using a shared resource, it is important to keep three things in mind:
+
+ 1. **The shared resource should be thread-safe.** This is because serverless
+    runtimes such as Google Cloud Functions may run multiple functions at a time
+    in separate threads.
+
+ 2. **Use `FunctionsFramework.on_startup` to initialize shared resources.**
+    Do not initialize a shared resource at the top level of your app. This is
+    because serverless runtimes may load your files (and thus execute any Ruby
+    code at the top level) in a build/deployment environment that may not be
+    equipped to support the resource. Instead, initialize resources in a
+    `FunctionsFramework.on_startup` block, which the Functions Framework will
+    call only just before starting a server.
+
+    For example:
+
+    ```ruby
+    require "functions_framework"
+
+    # This local variable is lexically shared among all blocks.
+    storage_client = nil
+
+    # Do not create the storage client here. This may run during deployment
+    # when, e.g., your storage credentials are not accessible.
+    #   require "google/cloud/storage"
+    #   storage_client = Google::Cloud::Storage.new # <- may fail
+
+    # Use an on_startup block to initialize the shared client.
+    # This block runs only when the framework is starting an actual server,
+    # and is guaranteed to complete before any functions are executed.
+    FunctionsFramework.on_startup do
+      require "google/cloud/storage"
+      storage_client = Google::Cloud::Storage.new
+    end
+
+    # The storage_client is shared among all function invocations
+    FunctionsFramework.http "storage_example" do |request|
+      bucket = storage_client.bucket "my-bucket"
+      file = bucket.file "path/to/my-file.txt"
+      file.download.to_s
+    end
+    ```
+
+ 3. **There is no guaranteed cleanup hook.** The Functions Framework does not
+    provide a guaranteed way to register a cleanup task. You can register a
+    `Kernel.at_exit` task, but remember that it is possible for the Ruby VM to
+    terminate without calling it. It is strongly recommended that you use
+    resources that do not require "cleanup".
+
 ## Structuring a project
 
 A Functions Framework based "project" or "application" is a typical Ruby

data/lib/functions_framework.rb

@@ -165,6 +165,29 @@ module FunctionsFramework
       self
     end
 
+    ##
+    # 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 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.
+    #
+    # @param block [Proc] The startup task
+    # @return [self]
+    #
+    def on_startup &block
+      global_registry.add_startup_task(&block)
+      self
+    end
+
     ##
     # Start the functions framework server in the background. The server will
     # look up the given target function name in the global registry.
@@ -184,6 +207,7 @@ module FunctionsFramework
         raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
       end
       server = Server.new function, &block
+      global_registry.run_startup_tasks server
       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.
@@ -52,7 +75,7 @@ module FunctionsFramework
     # @return [self]
     #
     def parse_args argv # rubocop:disable Metrics/MethodLength
-      option_parser = ::OptionParser.new do |op| # rubocop:disable Metrics/BlockLength
+      @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/registry.rb

@@ -25,8 +25,9 @@ module FunctionsFramework
     # Create a new empty registry.
     #
     def initialize
-      super()
+      @mutex = ::Monitor.new
       @functions = {}
+      @start_tasks = []
     end
 
     ##
@@ -37,7 +38,7 @@ module FunctionsFramework
     # @return [nil] if the function is not found
     #
     def [] name
-      @functions[name.to_s]
+      @mutex.synchronize { @functions[name.to_s] }
     end
 
     ##
@@ -46,7 +47,21 @@ module FunctionsFramework
     # @return [Array<String>]
     #
     def names
-      @functions.keys.sort
+      @mutex.synchronize { @functions.keys.sort }
+    end
+
+    ##
+    # Run all startup tasks.
+    #
+    # @param server [FunctionsFramework::Server] The server that is starting.
+    # @return [self]
+    #
+    def run_startup_tasks server
+      tasks = @mutex.synchronize { @start_tasks.dup }
+      tasks.each do |task|
+        task.call server.function, server.config
+      end
+      self
     end
 
     ##
@@ -68,7 +83,7 @@ module FunctionsFramework
     #
     def add_http name, &block
       name = name.to_s
-      synchronize do
+      @mutex.synchronize do
         raise ::ArgumentError, "Function already defined: #{name}" if @functions.key? name
         @functions[name] = Function.new name, :http, &block
       end
@@ -89,11 +104,29 @@ module FunctionsFramework
     #
     def add_cloud_event name, &block
       name = name.to_s
-      synchronize do
+      @mutex.synchronize do
         raise ::ArgumentError, "Function already defined: #{name}" if @functions.key? name
         @functions[name] = Function.new name, :cloud_event, &block
       end
       self
     end
+
+    ##
+    # Add a startup task.
+    #
+    # Startup tasks are generally run just before a server starts. They 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.
+    #
+    # @param block [Proc] The startup task
+    # @return [self]
+    #
+    def add_startup_task &block
+      @mutex.synchronize do
+        @start_tasks << block
+      end
+      self
+    end
   end
 end

data/lib/functions_framework/server.rb

@@ -82,9 +82,9 @@ module FunctionsFramework
           @server.max_threads = @config.max_threads
           @server.leak_stack_on_error = @config.show_error_details?
           @server.binder.add_tcp_listener @config.bind_addr, @config.port
-          @server.run true
           @config.logger.info "FunctionsFramework: Serving function #{@function.name.inspect}" \
                               " on port #{@config.port}..."
+          @server.run true
         end
       end
       self

data/lib/functions_framework/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-07 00:00:00.000000000 Z
+date: 2020-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cloud_events
@@ -87,10 +87,10 @@ homepage: https://github.com/GoogleCloudPlatform/functions-framework-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.5.2/file.CHANGELOG.html
+  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.6.0/file.CHANGELOG.html
   source_code_uri: https://github.com/GoogleCloudPlatform/functions-framework-ruby
   bug_tracker_uri: https://github.com/GoogleCloudPlatform/functions-framework-ruby/issues
-  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.5.2
+  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.6.0
 post_install_message: 
 rdoc_options: []
 require_paths: