functions_framework 0.5.0 → 0.7.1

data/lib/functions_framework/registry.rb

@@ -12,21 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "monitor"
-
 module FunctionsFramework
   ##
   # Registry providing lookup of functions by name.
   #
   class Registry
-    include ::MonitorMixin
-
     ##
     # Create a new empty registry.
     #
     def initialize
-      super()
+      @mutex = ::Mutex.new
       @functions = {}
+      @start_tasks = []
     end
 
     ##
@@ -37,7 +34,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 +43,16 @@ module FunctionsFramework
     # @return [Array<String>]
     #
     def names
-      @functions.keys.sort
+      @mutex.synchronize { @functions.keys.sort }
+    end
+
+    ##
+    # Return an array of startup tasks.
+    #
+    # @return [Array<FunctionsFramework::Function>]
+    #
+    def startup_tasks
+      @mutex.synchronize { @start_tasks.dup }
     end
 
     ##
@@ -68,9 +74,9 @@ 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
+        @functions[name] = Function.http name, &block
       end
       self
     end
@@ -80,7 +86,7 @@ module FunctionsFramework
     #
     # You must provide a name for the function, and a block that implemets the
     # function. The block should take _one_ argument: the event object of type
-    # [`CloudEvents::Event`](https://rubydoc.info/gems/cloud_events/CloudEvents/Event).
+    # [`CloudEvents::Event`](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event).
     # Any return value is ignored.
     #
     # @param name [String] The function name
@@ -89,9 +95,26 @@ 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
+        @functions[name] = Function.cloud_event name, &block
+      end
+      self
+    end
+
+    ##
+    # Add a startup task.
+    #
+    # Startup tasks are generally run just before a server starts. They are
+    # passed the {FunctionsFramework::Function} identifying the function to
+    # execute, and have no return value.
+    #
+    # @param block [Proc] The startup task
+    # @return [self]
+    #
+    def add_startup_task &block
+      @mutex.synchronize do
+        @start_tasks << Function.startup_task(&block)
       end
       self
     end

data/lib/functions_framework/server.rb

@@ -27,17 +27,22 @@ module FunctionsFramework
     include ::MonitorMixin
 
     ##
-    # Create a new web server given a function. Yields a
-    # {FunctionsFramework::Server::Config} object that you can use to set
-    # server configuration parameters. This block is the only opportunity to
-    # set configuration; once the server is initialized, configuration is
-    # frozen.
+    # Create a new web server given a function definition, a set of application
+    # globals, and server configuration.
+    #
+    # To configure the server, pass a block that takes a
+    # {FunctionsFramework::Server::Config} object as the parameter. This block
+    # is the only opportunity to modify the configuration; once the server is
+    # initialized, configuration is frozen.
     #
     # @param function [FunctionsFramework::Function] The function to execute.
+    # @param globals [Hash] Globals to pass to invocations. This hash should
+    #     normally be frozen so separate function invocations cannot interfere
+    #     with one another's globals.
     # @yield [FunctionsFramework::Server::Config] A config object that can be
     #     manipulated to configure this server.
     #
-    def initialize function
+    def initialize function, globals
       super()
       @config = Config.new
       yield @config if block_given?
@@ -46,9 +51,9 @@ module FunctionsFramework
       @app =
         case function.type
         when :http
-          HttpApp.new function, @config
+          HttpApp.new function, globals, @config
         when :cloud_event
-          EventApp.new function, @config
+          EventApp.new function, globals, @config
         else
           raise "Unrecognized function type: #{function.type}"
         end
@@ -82,9 +87,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
@@ -379,9 +384,10 @@ module FunctionsFramework
 
     ## @private
     class HttpApp < AppBase
-      def initialize function, config
+      def initialize function, globals, config
         super config
         @function = function
+        @globals = globals
       end
 
       def call env
@@ -391,8 +397,7 @@ module FunctionsFramework
             logger = env["rack.logger"] ||= @config.logger
             request = ::Rack::Request.new env
             logger.info "FunctionsFramework: Handling HTTP #{request.request_method} request"
-            calling_context = @function.new_call logger: logger
-            calling_context.call request
+            @function.call request, globals: @globals, logger: logger
           rescue ::StandardError => e
             e
           end
@@ -402,9 +407,10 @@ module FunctionsFramework
 
     ## @private
     class EventApp < AppBase
-      def initialize function, config
+      def initialize function, globals, config
         super config
         @function = function
+        @globals = globals
         @cloud_events = ::CloudEvents::HttpBinding.default
         @legacy_events = LegacyEventConverter.new
       end
@@ -439,8 +445,7 @@ module FunctionsFramework
 
       def handle_cloud_event event, logger
         logger.info "FunctionsFramework: Handling CloudEvent"
-        calling_context = @function.new_call logger: logger
-        calling_context.call event
+        @function.call event, globals: @globals, logger: logger
         "ok"
       rescue ::StandardError => e
         e

data/lib/functions_framework/testing.rb

@@ -75,19 +75,71 @@ module FunctionsFramework
       Testing.load_for_testing path, &block
     end
 
+    ##
+    # Run startup tasks for the given function name and return the initialized
+    # globals hash.
+    #
+    # Normally, this will be run automatically prior to the first call to the
+    # function using {call_http} or {call_event}, if it has not already been
+    # run. However, you can call it explicitly to test its behavior. It cannot
+    # be called more than once for any given function.
+    #
+    # By default, the {FunctionsFramework.logger} will be used, but you can
+    # override that by providing your own logger. In particular, to disable
+    # logging, you can pass `Logger.new(nil)`.
+    #
+    # @param name [String] The name of the function to start up.
+    # @param logger [Logger] Use the given logger instead of the Functions
+    #     Framework's global logger. Optional.
+    # @param lenient [Boolean] If false (the default), raise an error if the
+    #     given function has already had its startup tasks run. If true,
+    #     duplicate requests to run startup tasks are ignored.
+    # @return [Hash] The initialized globals.
+    #
+    def run_startup_tasks name, logger: nil, lenient: false
+      function = Testing.current_registry[name]
+      raise "Unknown function name #{name}" unless function
+      globals = Testing.current_globals name
+      if globals
+        raise "Function #{name} has already been started up" unless lenient
+      else
+        globals = function.populate_globals
+        Testing.current_registry.startup_tasks.each do |task|
+          task.call function, globals: globals, logger: logger
+        end
+        Testing.current_globals name, globals
+      end
+      globals.freeze
+    end
+
     ##
     # Call the given HTTP function for testing. The underlying function must
-    # be of type `:http`.
+    # be of type `:http`. Returns the Rack response.
+    #
+    # By default, the startup tasks will be run for the given function if they
+    # have not already been run. You can, however, disable running startup
+    # tasks by providing an explicit globals hash.
+    #
+    # By default, the {FunctionsFramework.logger} will be used, but you can
+    # override that by providing your own logger. In particular, to disable
+    # logging, you can pass `Logger.new(nil)`.
     #
     # @param name [String] The name of the function to call
     # @param request [Rack::Request] The Rack request to send
+    # @param globals [Hash] Do not run startup tasks, and instead provide the
+    #     globals directly. Optional.
+    # @param logger [Logger] Use the given logger instead of the Functions
+    #     Framework's global logger. Optional.
     # @return [Rack::Response]
     #
-    def call_http name, request
-      function = ::FunctionsFramework.global_registry[name]
+    def call_http name, request, globals: nil, logger: nil
+      globals ||= run_startup_tasks name, logger: logger, lenient: true
+      function = Testing.current_registry[name]
       case function&.type
       when :http
-        Testing.interpret_response { function.new_call.call request }
+        Testing.interpret_response do
+          function.call request, globals: globals, logger: logger
+        end
       when nil
         raise "Unknown function name #{name}"
       else
@@ -99,15 +151,28 @@ module FunctionsFramework
     # Call the given event function for testing. The underlying function must
     # be of type :cloud_event`.
     #
+    # By default, the startup tasks will be run for the given function if they
+    # have not already been run. You can, however, disable running startup
+    # tasks by providing an explicit globals hash.
+    #
+    # By default, the {FunctionsFramework.logger} will be used, but you can
+    # override that by providing your own logger. In particular, to disable
+    # logging, you can pass `Logger.new(nil)`.
+    #
     # @param name [String] The name of the function to call
     # @param event [::CloudEvents::Event] The event to send
+    # @param globals [Hash] Do not run startup tasks, and instead provide the
+    #     globals directly. Optional.
+    # @param logger [Logger] Use the given logger instead of the Functions
+    #     Framework's global logger. Optional.
     # @return [nil]
     #
-    def call_event name, event
-      function = ::FunctionsFramework.global_registry[name]
+    def call_event name, event, globals: nil, logger: nil
+      globals ||= run_startup_tasks name, logger: logger, lenient: true
+      function = Testing.current_registry[name]
       case function&.type
       when :cloud_event
-        function.new_call.call event
+        function.call event, globals: globals, logger: logger
         nil
       when nil
         raise "Unknown function name #{name}"
@@ -208,27 +273,49 @@ module FunctionsFramework
     extend self
 
     @testing_registries = {}
+    @main_globals = {}
     @mutex = ::Mutex.new
 
     class << self
       ## @private
       def load_for_testing path
         old_registry = ::FunctionsFramework.global_registry
-        @mutex.synchronize do
-          if @testing_registries.key? path
-            ::FunctionsFramework.global_registry = @testing_registries[path]
-          else
-            new_registry = ::FunctionsFramework::Registry.new
-            ::FunctionsFramework.global_registry = new_registry
-            ::Kernel.load path
-            @testing_registries[path] = new_registry
+        ::Thread.current[:functions_framework_testing_registry] =
+          @mutex.synchronize do
+            if @testing_registries.key? path
+              ::FunctionsFramework.global_registry = @testing_registries[path]
+            else
+              new_registry = ::FunctionsFramework::Registry.new
+              ::FunctionsFramework.global_registry = new_registry
+              ::Kernel.load path
+              @testing_registries[path] = new_registry
+            end
           end
-        end
+        ::Thread.current[:functions_framework_testing_globals] = {}
         yield
       ensure
+        ::Thread.current[:functions_framework_testing_registry] = nil
+        ::Thread.current[:functions_framework_testing_globals] = nil
         ::FunctionsFramework.global_registry = old_registry
       end
 
+      ## @private
+      def current_registry
+        ::Thread.current[:functions_framework_testing_registry] ||
+          ::FunctionsFramework.global_registry
+      end
+
+      ## @private
+      def current_globals name, globals = nil
+        name = name.to_s
+        globals_by_name = ::Thread.current[:functions_framework_testing_globals] || @main_globals
+        if globals
+          globals_by_name[name] = globals
+        else
+          globals_by_name[name]
+        end
+      end
+
       ## @private
       def interpret_response
         response =

data/lib/functions_framework/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-09 00:00:00.000000000 Z
+date: 2021-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cloud_events
@@ -52,7 +52,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
-description: The Functions Framework implementation for Ruby.
+description: The Functions Framework is an open source framework for writing lightweight,
+  portable Ruby functions that run in a serverless environment. Functions written
+  to this Framework will run on Google Cloud Functions, Google Cloud Run, or any other
+  Knative-based environment.
 email:
 - dazuma@google.com
 executables:
@@ -84,10 +87,10 @@ homepage: https://github.com/GoogleCloudPlatform/functions-framework-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://github.com/GoogleCloudPlatform/functions-framework-ruby/blob/master/CHANGELOG.md
+  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.7.1/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://rubydoc.info/gems/functions_framework/0.5.0
+  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.7.1
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -96,14 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Functions Framework for Ruby