functions_framework 0.4.0 → 0.6.0

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/function.rb

@@ -23,8 +23,9 @@ module FunctionsFramework
   # `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
-  # {FunctionsFramework::CloudEvents::Event CloudEvent} argument, and does not
-  # return a value. See {FunctionsFramework::Registry.add_cloud_event}.
+  # [CloudEvent](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event)
+  # argument, and does not return a value.
+  # See {FunctionsFramework::Registry.add_cloud_event}.
   #
   # 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

data/lib/functions_framework/legacy_event_converter.rb

@@ -23,19 +23,17 @@ 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
-      raw_context = input["context"] || input
-      context = normalized_context raw_context
+      context = normalized_context input
       return nil unless context
-      construct_cloud_event context, input["data"]
+      construct_cloud_event context, input["data"], content_type.charset
     end
 
     private
@@ -50,27 +48,27 @@ module FunctionsFramework
       nil
     end
 
-    def normalized_context raw_context
-      id = raw_context["eventId"]
-      return nil unless id
-      timestamp = raw_context["timestamp"]
-      return nil unless timestamp
-      type = raw_context["eventType"]
-      return nil unless type
-      service, resource = analyze_resource raw_context["resource"], type
-      return nil unless service && resource
+    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"]
+      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 analyze_resource raw_resource, type
+    def analyze_resource raw_resource
+      service = resource = nil
       case raw_resource
       when ::Hash
-        [raw_resource["service"], raw_resource["name"]]
+        service = raw_resource["service"]
+        resource = raw_resource["name"]
       when ::String
-        [service_from_type(type), raw_resource]
-      else
-        [nil, nil]
+        resource = raw_resource
       end
+      [service, resource]
     end
 
     def service_from_type type
@@ -80,19 +78,20 @@ module FunctionsFramework
       nil
     end
 
-    def construct_cloud_event context, data
+    def construct_cloud_event context, data, charset
       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
-      CloudEvents::Event.new id:                context[:id],
-                             source:            source,
-                             type:              type,
-                             spec_version:      "1.0",
-                             data_content_type: "application/json",
-                             data:              ce_data,
-                             subject:           subject,
-                             time:              context[:timestamp]
+      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]
     end
 
     def convert_source service, resource

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
@@ -80,7 +95,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,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
@@ -149,8 +149,12 @@ module FunctionsFramework
         ::Signal.trap "SIGINT" do
           Server.signal_enqueue "SIGINT", @config.logger, @server
         end
-        ::Signal.trap "SIGHUP" do
-          Server.signal_enqueue "SIGHUP", @config.logger, @server
+        begin
+          ::Signal.trap "SIGHUP" do
+            Server.signal_enqueue "SIGHUP", @config.logger, @server
+          end
+        rescue ::ArgumentError # rubocop:disable Lint/HandleExceptions
+          # Not available on all systems
         end
         @signals_installed = true
       end
@@ -340,7 +344,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"
@@ -401,7 +405,7 @@ module FunctionsFramework
       def initialize function, config
         super config
         @function = function
-        @cloud_events = CloudEvents::HttpBinding.default
+        @cloud_events = ::CloudEvents::HttpBinding.default
         @legacy_events = LegacyEventConverter.new
       end
 
@@ -411,11 +415,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}"
@@ -428,8 +432,8 @@ 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