functions_framework 0.4.1 → 0.7.0

data/lib/functions_framework/legacy_event_converter.rb

@@ -23,12 +23,11 @@ module FunctionsFramework
     # 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 [::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"]
+      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
@@ -85,14 +84,14 @@ module FunctionsFramework
       return nil unless type && source
       ce_data = convert_data context[:service], data
       content_type = "application/json; charset=#{charset}"
-      CloudEvents::Event.new id:                context[:id],
-                             source:            source,
-                             type:              type,
-                             spec_version:      "1.0",
-                             data_content_type: content_type,
-                             data:              ce_data,
-                             subject:           subject,
-                             time:              context[:timestamp]
+      ::CloudEvents::Event.new id:                context[:id],
+                               source:            source,
+                               type:              type,
+                               spec_version:      "1.0",
+                               data_content_type: content_type,
+                               data:              ce_data,
+                               subject:           subject,
+                               time:              context[:timestamp]
     end
 
     def convert_source service, resource

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,8 @@ 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
-    # {FunctionsFramework::CloudEvents::Event}. Any return value is ignored.
+    # [`CloudEvents::Event`](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event).
+    # Any return value is ignored.
     #
     # @param name [String] The function name
     # @param block [Proc] The function code as a proc
@@ -88,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
@@ -344,7 +349,7 @@ module FunctionsFramework
           string_response response, "text/plain", 200
         when ::Hash
           string_response ::JSON.dump(response), "application/json", 200
-        when CloudEvents::CloudEventsError
+        when ::CloudEvents::CloudEventsError
           cloud_events_error_response response
         when ::StandardError
           error_response "#{response.class}: #{response.message}\n#{response.backtrace}\n"
@@ -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,10 +407,11 @@ module FunctionsFramework
 
     ## @private
     class EventApp < AppBase
-      def initialize function, config
+      def initialize function, globals, config
         super config
         @function = function
-        @cloud_events = CloudEvents::HttpBinding.default
+        @globals = globals
+        @cloud_events = ::CloudEvents::HttpBinding.default
         @legacy_events = LegacyEventConverter.new
       end
 
@@ -415,11 +421,11 @@ module FunctionsFramework
         event = decode_event env
         response =
           case event
-          when CloudEvents::Event
+          when ::CloudEvents::Event
             handle_cloud_event event, logger
           when ::Array
-            CloudEvents::HttpContentError.new "Batched CloudEvents are not supported"
-          when CloudEvents::CloudEventsError
+            ::CloudEvents::HttpContentError.new "Batched CloudEvents are not supported"
+          when ::CloudEvents::CloudEventsError
             event
           else
             raise "Unexpected event type: #{event.class}"
@@ -432,15 +438,14 @@ module FunctionsFramework
       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
+          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
+        @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 [FunctionsFramework::CloudEvets::Event] The event to send
+    # @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}"
@@ -174,49 +239,83 @@ module FunctionsFramework
     # @param source [String,URI] Event source (optional)
     # @param type [String] Event type (optional)
     # @param spec_version [String] Spec version (optional)
-    # @param data_content_type [String,FunctionsFramework::CloudEvents::ContentType]
+    # @param data_content_type [String,::CloudEvents::ContentType]
     #     Content type for the data (optional)
     # @param data_schema [String,URI] Data schema (optional)
     # @param subject [String] Subject (optional)
     # @param time [String,DateTime] Event timestamp (optional)
-    # @return [FunctionsFramework::CloudEvents::Event]
+    # @return [::CloudEvents::Event]
     #
     def make_cloud_event data,
-                         id: nil, source: nil, type: nil, spec_version: nil,
-                         data_content_type: nil, data_schema: nil, subject: nil, time: nil
+                         id: nil,
+                         source: nil,
+                         type: nil,
+                         spec_version: nil,
+                         data_content_type: nil,
+                         data_schema: nil,
+                         subject: nil,
+                         time: nil
       id ||= "random-id-#{rand 100_000_000}"
       source ||= "functions-framework-testing"
       type ||= "com.example.test"
       spec_version ||= "1.0"
-      CloudEvents::Event.new id: id, source: source, type: type, spec_version: spec_version,
-                             data_content_type: data_content_type, data_schema: data_schema,
-                             subject: subject, time: time, data: data
+      ::CloudEvents::Event.new id:                id,
+                               source:            source,
+                               type:              type,
+                               spec_version:      spec_version,
+                               data_content_type: data_content_type,
+                               data_schema:       data_schema,
+                               subject:           subject,
+                               time:              time,
+                               data:              data
     end
 
     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 =