functions_framework 0.1.1 → 0.4.0

data/lib/functions_framework.rb

@@ -16,6 +16,7 @@ require "logger"
 
 require "functions_framework/cloud_events"
 require "functions_framework/function"
+require "functions_framework/legacy_event_converter"
 require "functions_framework/registry"
 require "functions_framework/version"
 
@@ -36,8 +37,8 @@ require "functions_framework/version"
 # functions framework. Use the {FunctionsFramework.http},
 # {FunctionsFramework.event}, or {FunctionsFramework.cloud_event} methods to
 # define functions. To serve functions via a web service, invoke the
-# `functions-framework` executable, or use the {FunctionsFramework.start} or
-# {FunctionsFramework.run} methods.
+# `functions-framework-ruby` executable, or use the {FunctionsFramework.start}
+# or {FunctionsFramework.run} methods.
 #
 # ## Internal modules
 #
@@ -48,7 +49,7 @@ require "functions_framework/version"
 #     you define an event function, you will receive the event as a
 #     {FunctionsFramework::CloudEvents::Event} object.
 #  *  {FunctionsFramework::CLI} is the implementation of the
-#     `functions-framework` executable. Most apps will not need to interact
+#     `functions-framework-ruby` executable. Most apps will not need to interact
 #     with this class directly.
 #  *  {FunctionsFramework::Function} is the internal representation of a
 #     function, indicating the type of function (http or cloud event), the
@@ -62,7 +63,7 @@ require "functions_framework/version"
 #  *  {FunctionsFramework::Server} is a web server that makes a function
 #     available via HTTP. It wraps the Puma web server and runs a specific
 #     {FunctionsFramework::Function}. Many apps can simply run the
-#     `functions-framework` executable to spin up a server. However, if you
+#     `functions-framework-ruby` executable to spin up a server. However, if you
 #     need closer control over your execution environment, you can use the
 #     {FunctionsFramework::Server} class to run a server. Note that, in most
 #     cases, it is easier to use the {FunctionsFramework.start} or
@@ -142,50 +143,9 @@ module FunctionsFramework
     # Define a function that responds to CloudEvents.
     #
     # You must provide a name for the function, and a block that implemets the
-    # function. The block should take two arguments: the event _data_ and the
-    # event _context_. Any return value is ignored.
-    #
-    # The event data argument will be one of the following types:
-    #  *  A `String` (with encoding `ASCII-8BIT`) if the data is in the form of
-    #     binary data. You may choose to perform additional interpretation of
-    #     the binary data using information in the content type provided by the
-    #     context argument.
-    #  *  Any data type that can be represented in JSON (i.e. `String`,
-    #     `Integer`, `Array`, `Hash`, `true`, `false`, or `nil`) if the event
-    #     came with a JSON payload. The content type may also be set in the
-    #     context if the data is a String.
-    #
-    # The context argument will be of type {FunctionsFramework::CloudEvents::Event},
-    # and will contain CloudEvents context attributes such as `id` and `type`.
-    #
-    # See also {FunctionsFramework.cloud_event} which defines a function that
-    # takes a single argument of type {FunctionsFramework::CloudEvents::Event}.
-    #
-    # ## Example
-    #
-    #     FunctionsFramework.event "my-function" do |data, context|
-    #       FunctionsFramework.logger.info "Event data: #{data.inspect}"
-    #     end
-    #
-    # @param name [String] The function name. Defaults to {DEFAULT_TARGET}.
-    # @param block [Proc] The function code as a proc.
-    # @return [self]
-    #
-    def event name = DEFAULT_TARGET, &block
-      global_registry.add_event name, &block
-      self
-    end
-
-    ##
-    # Define a function that responds to CloudEvents.
-    #
-    # 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
+    # function. The block should take one argument: the event object of type
     # {FunctionsFramework::CloudEvents::Event}. Any return value is ignored.
     #
-    # See also {FunctionsFramework.event} which creates a function that takes
-    # data and context as separate arguments.
-    #
     # ## Example
     #
     #     FunctionsFramework.cloud_event "my-function" do |event|
@@ -205,15 +165,20 @@ module FunctionsFramework
     # Start the functions framework server in the background. The server will
     # look up the given target function name in the global registry.
     #
-    # @param target [String] The name of the function to run
+    # @param target [FunctionsFramework::Function,String] The function to run,
+    #     or the name of the function to look up in the global registry.
     # @yield [FunctionsFramework::Server::Config] A config object that can be
     #     manipulated to configure the server.
     # @return [FunctionsFramework::Server]
     #
     def start target, &block
       require "functions_framework/server"
-      function = global_registry[target]
-      raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
+      if target.is_a? ::FunctionsFramework::Function
+        function = target
+      else
+        function = global_registry[target]
+        raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
+      end
       server = Server.new function, &block
       server.respond_to_signals
       server.start
@@ -223,7 +188,8 @@ module FunctionsFramework
     # Run the functions framework server and block until it stops. The server
     # will look up the given target function name in the global registry.
     #
-    # @param target [String] The name of the function to run
+    # @param target [FunctionsFramework::Function,String] The function to run,
+    #     or the name of the function to look up in the global registry.
     # @yield [FunctionsFramework::Server::Config] A config object that can be
     #     manipulated to configure the server.
     # @return [self]

data/lib/functions_framework/cli.rb

@@ -12,15 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "logger"
 require "optparse"
 
 require "functions_framework"
 
 module FunctionsFramework
   ##
-  # Implementation of the functions-framework executable.
+  # Implementation of the functions-framework-ruby executable.
   #
   class CLI
+    ##
+    # The default logging level, if not given in the environment variable.
+    # @return [Integer]
+    #
+    DEFAULT_LOGGING_LEVEL = ::Logger::Severity::INFO
+
     ##
     # Create a new CLI, setting arguments to their defaults.
     #
@@ -33,6 +40,8 @@ module FunctionsFramework
       @min_threads = nil
       @max_threads = nil
       @detailed_errors = nil
+      @signature_type = ::ENV["FUNCTION_SIGNATURE_TYPE"]
+      @logging_level = init_logging_level
     end
 
     ##
@@ -52,6 +61,11 @@ module FunctionsFramework
               "Set the source file to load (defaults to #{DEFAULT_SOURCE})" do |val|
           @source = val
         end
+        op.on "--signature-type TYPE",
+              "Asserts that the function has the given signature type." \
+              " Supported values are 'http' and 'cloudevent'." do |val|
+          @signature_type = val
+        end
         op.on "-p", "--port PORT", "Set the port to listen to (defaults to 8080)" do |val|
           @port = val.to_i
         end
@@ -71,10 +85,10 @@ module FunctionsFramework
           @detailed_errors = val
         end
         op.on "-v", "--verbose", "Increase log verbosity" do
-          ::FunctionsFramework.logger.level -= 1
+          @logging_level -= 1
         end
         op.on "-q", "--quiet", "Decrease log verbosity" do
-          ::FunctionsFramework.logger.level += 1
+          @logging_level += 1
         end
         op.on "--help", "Display help" do
           puts op
@@ -82,23 +96,51 @@ module FunctionsFramework
         end
       end
       option_parser.parse! argv
-      unless argv.empty?
-        warn "Unrecognized arguments: #{argv}"
-        puts op
-        exit 1
-      end
+      error "Unrecognized arguments: #{argv}\n#{op}" unless argv.empty?
       self
     end
 
     ##
     # Run the configured server, and block until it stops.
+    # If a validation error occurs, print a message and exit.
+    #
     # @return [self]
     #
     def run
-      FunctionsFramework.logger.info \
-        "FunctionsFramework: Loading functions from #{@source.inspect}..."
+      begin
+        server = start_server
+      rescue ::StandardError => e
+        error e.message
+      end
+      server.wait_until_stopped
+      self
+    end
+
+    ##
+    # Start the configured server and return the running server object.
+    # If a validation error occurs, raise an exception.
+    # This is used for testing the CLI.
+    #
+    # @return [FunctionsFramework::Server]
+    #
+    # @private
+    #
+    def start_server
+      ::FunctionsFramework.logger.level = @logging_level
+      ::FunctionsFramework.logger.info "FunctionsFramework v#{VERSION} server starting."
+      ::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
-      server = ::FunctionsFramework.start @target do |config|
+      function = ::FunctionsFramework.global_registry[@target]
+      raise "Undefined function: #{@target.inspect}" if function.nil?
+      unless @signature_type.nil? ||
+             @signature_type == "http" && function.type == :http ||
+             ["cloudevent", "event"].include?(@signature_type) && function.type == :cloud_event
+        raise "Function #{@target.inspect} does not match type #{@signature_type}"
+      end
+      ::FunctionsFramework.start function do |config|
         config.rack_env = @env
         config.port = @port
         config.bind_addr = @bind
@@ -106,8 +148,24 @@ module FunctionsFramework
         config.min_threads = @min_threads
         config.max_threads = @max_threads
       end
-      server.wait_until_stopped
-      self
+    end
+
+    private
+
+    def init_logging_level
+      level_name = ::ENV["FUNCTION_LOGGING_LEVEL"].to_s.upcase.to_sym
+      ::Logger::Severity.const_get level_name
+    rescue ::NameError
+      DEFAULT_LOGGING_LEVEL
+    end
+
+    ##
+    # Print the given error message and exit.
+    # @param message [String]
+    #
+    def error message
+      warn message
+      exit 1
     end
   end
 end

data/lib/functions_framework/cloud_events.rb

@@ -12,132 +12,34 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "functions_framework/cloud_events/binary_content"
 require "functions_framework/cloud_events/content_type"
+require "functions_framework/cloud_events/errors"
 require "functions_framework/cloud_events/event"
+require "functions_framework/cloud_events/http_binding"
+require "functions_framework/cloud_events/json_format"
 
 module FunctionsFramework
   ##
   # CloudEvents implementation.
   #
   # This is a Ruby implementation of the [CloudEvents](https://cloudevents.io)
-  # [1.0 specification](https://github.com/cloudevents/spec/blob/master/spec.md).
-  # It provides for unmarshaling of events from Rack environment data from
-  # binary (i.e. header-based) format, as well as structured (body-based) and
-  # batch formats. A standard JSON structure parser is included. It is also
-  # possible to register handlers for other formats.
-  #
-  # TODO: Unmarshaling of events is implemented, but marshaling is not.
+  # specification. It supports both
+  # [CloudEvents 0.3](https://github.com/cloudevents/spec/blob/v0.3/spec.md) and
+  # [CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md).
   #
   module CloudEvents
-    @structured_formats = {}
-    @batched_formats = {}
+    # @private
+    SUPPORTED_SPEC_VERSIONS = ["0.3", "1.0"].freeze
 
     class << self
       ##
-      # Register a handler for the given structured format.
-      # The handler object must respond to the method
-      # `#decode_structured_content`. See
-      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
-      #
-      # @param format [String] The subtype format that should be handled by
-      #     this handler
-      # @param handler [#decode_structured_content] The handler object
-      # @return [self]
-      #
-      def register_structured_format format, handler
-        handlers = @structured_formats[format.to_s.strip.downcase] ||= []
-        handlers << handler unless handlers.include? handler
-        self
-      end
-
-      ##
-      # Register a handler for the given batched format.
-      # The handler object must respond to the method
-      # `#decode_batched_content`. See
-      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
+      # The spec versions supported by this implementation.
       #
-      # @param format [String] The subtype format that should be handled by
-      #     this handler
-      # @param handler [#decode_batched_content] The handler object
-      # @return [self]
+      # @return [Array<String>]
       #
-      def register_batched_format format, handler
-        handlers = @batched_formats[format.to_s.strip.downcase] ||= []
-        handlers << handler unless handlers.include? handler
-        self
-      end
-
-      ##
-      # Decode an event from the given Rack environment hash. Following the
-      # CloudEvents spec, this chooses a handler based on the Content-Type of
-      # the request.
-      #
-      # @param env [Hash] The Rack environment
-      # @return [FunctionsFramework::CloudEvents::Event] if the request
-      #     includes a single structured or binary event
-      # @return [Array<FunctionsFramework::CloudEvents::Event>] if the request
-      #     includes a batch of structured events
-      #
-      def decode_rack_env env
-        content_type_header = env["CONTENT_TYPE"]
-        raise "Missing content-type header" unless content_type_header
-        content_type = ContentType.new content_type_header
-        if content_type.media_type == "application"
-          case content_type.subtype_prefix
-          when "cloudevents"
-            return decode_structured_content env["rack.input"], content_type
-          when "cloudevents-batch"
-            return decode_batched_content env["rack.input"], content_type
-          end
-        end
-        BinaryContent.decode_rack_env env, content_type
-      end
-
-      ##
-      # Decode a single event from the given content data. This should be
-      # passed the request body, if the Content-Type is of the form
-      # `application/cloudevents+format`.
-      #
-      # @param input [IO] An IO-like object providing the content
-      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
-      #     content type
-      # @return [FunctionsFramework::CloudEvents::Event]
-      #
-      def decode_structured_content input, content_type
-        handlers = @structured_formats[content_type.subtype_format] || []
-        handlers.reverse_each do |handler|
-          event = handler.decode_structured_content input, content_type
-          return event if event
-        end
-        raise "Unknown cloudevents format: #{content_type.subtype_format.inspect}"
-      end
-
-      ##
-      # Decode a batch of events from the given content data. This should be
-      # passed the request body, if the Content-Type is of the form
-      # `application/cloudevents-batch+format`.
-      #
-      # @param input [IO] An IO-like object providing the content
-      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
-      #     content type
-      # @return [Array<FunctionsFramework::CloudEvents::Event>]
-      #
-      def decode_batched_content input, content_type
-        handlers = @batched_formats[content_type.subtype_format] || []
-        handlers.reverse_each do |handler|
-          events = handler.decode_batched_content input, content_type
-          return events if events
-        end
-        raise "Unknown cloudevents batch format: #{content_type.subtype_format.inspect}"
+      def supported_spec_versions
+        SUPPORTED_SPEC_VERSIONS
       end
     end
   end
 end
-
-require "functions_framework/cloud_events/json_structure"
-
-FunctionsFramework::CloudEvents.register_structured_format \
-  "json", FunctionsFramework::CloudEvents::JsonStructure
-FunctionsFramework::CloudEvents.register_batched_format \
-  "json", FunctionsFramework::CloudEvents::JsonStructure

data/lib/functions_framework/cloud_events/content_type.rb

@@ -23,29 +23,31 @@ module FunctionsFramework
     # Case-insensitive fields, such as media_type and subtype, are normalized
     # to lower case.
     #
+    # If parsing fails, this class will try to get as much information as it
+    # can, and fill the rest with defaults as recommended in RFC 2045 sec 5.2.
+    # In case of a parsing error, the {#error_message} field will be set.
+    #
     class ContentType
       ##
-      # Parse the given header value
+      # Parse the given header value.
       #
       # @param string [String] Content-Type header value in RFC 2045 format
       #
       def initialize string
         @string = string
-        # TODO: This handles simple cases but is not RFC-822 compliant.
-        sections = string.to_s.split ";"
-        media_type, subtype = sections.shift.split "/"
-        subtype_prefix, subtype_format = subtype.split "+"
-        @media_type = media_type.strip.downcase
-        @subtype = subtype.strip.downcase
-        @subtype_prefix = subtype_prefix.strip.downcase
-        @subtype_format = subtype_format&.strip&.downcase
-        @params = initialize_params sections
+        @media_type = "text"
+        @subtype_base = @subtype = "plain"
+        @subtype_format = nil
+        @params = []
+        @charset = "us-ascii"
+        @error_message = nil
+        parse consume_comments string.strip
         @canonical_string = "#{@media_type}/#{@subtype}" +
                             @params.map { |k, v| "; #{k}=#{v}" }.join
       end
 
       ##
-      # The original header content string
+      # The original header content string.
       # @return [String]
       #
       attr_reader :string
@@ -66,7 +68,7 @@ module FunctionsFramework
 
       ##
       # The entire content subtype (which could include an extension delimited
-      # by a plus sign)
+      # by a plus sign).
       # @return [String]
       #
       attr_reader :subtype
@@ -75,7 +77,7 @@ module FunctionsFramework
       # The portion of the content subtype before any plus sign.
       # @return [String]
       #
-      attr_reader :subtype_prefix
+      attr_reader :subtype_base
 
       ##
       # The portion of the content subtype after any plus sign, or nil if there
@@ -91,6 +93,18 @@ module FunctionsFramework
       #
       attr_reader :params
 
+      ##
+      # The charset, defaulting to "us-ascii" if none is explicitly set.
+      # @return [String]
+      #
+      attr_reader :charset
+
+      ##
+      # The error message when parsing, or `nil` if there was no error message.
+      # @return [String,nil]
+      #
+      attr_reader :error_message
+
       ##
       # An array of values for the given parameter name
       # @param key [String]
@@ -101,15 +115,6 @@ module FunctionsFramework
         @params.inject([]) { |a, (k, v)| key == k ? a << v : a }
       end
 
-      ##
-      # The first value of the "charset" parameter, or nil if there is no
-      # charset.
-      # @return [String,nil]
-      #
-      def charset
-        param_values("charset").first
-      end
-
       ## @private
       def == other
         other.is_a?(ContentType) && canonical_string == other.canonical_string
@@ -121,18 +126,90 @@ module FunctionsFramework
         canonical_string.hash
       end
 
+      ## @private
+      class ParseError < ::StandardError
+      end
+
       private
 
-      def initialize_params sections
-        params = sections.map do |s|
-          k, v = s.split "="
-          [k.strip.downcase, v.strip]
+      def parse str
+        @media_type, str = consume_token str, downcase: true, error_message: "Failed to parse media type"
+        str = consume_special str, "/"
+        @subtype, str = consume_token str, downcase: true, error_message: "Failed to parse subtype"
+        @subtype_base, @subtype_format = @subtype.split "+", 2
+        until str.empty?
+          str = consume_special str, ";"
+          name, str = consume_token str, downcase: true, error_message: "Faled to parse attribute name"
+          str = consume_special str, "=", error_message: "Failed to find value for attribute #{name}"
+          val, str = consume_token_or_quoted str, error_message: "Failed to parse value for attribute #{name}"
+          @params << [name, val]
+          @charset = val if name == "charset"
         end
-        params.sort! do |(k1, v1), (k2, v2)|
-          a = k1 <=> k2
-          a.zero? ? v1 <=> v2 : a
+      rescue ParseError => e
+        @error_message = e.message
+      end
+
+      def consume_token str, downcase: false, error_message: nil
+        match = /^([\w!#\$%&'\*\+\.\^`\{\|\}-]+)(.*)$/.match str
+        raise ParseError, error_message || "Expected token" unless match
+        token = match[1]
+        token.downcase! if downcase
+        str = consume_comments match[2].strip
+        [token, str]
+      end
+
+      def consume_special str, expected, error_message: nil
+        raise ParseError, error_message || "Expected #{expected.inspect}" unless str.start_with? expected
+        consume_comments str[1..-1].strip
+      end
+
+      def consume_token_or_quoted str, error_message: nil
+        return consume_token str unless str.start_with? '"'
+        arr = []
+        index = 1
+        loop do
+          char = str[index]
+          case char
+          when nil
+            raise ParseError, error_message || "Quoted-string never finished"
+          when "\""
+            break
+          when "\\"
+            char = str[index + 1]
+            raise ParseError, error_message || "Quoted-string never finished" unless char
+            arr << char
+            index += 2
+          else
+            arr << char
+            index += 1
+          end
+        end
+        index += 1
+        str = consume_comments str[index..-1].strip
+        [arr.join, str]
+      end
+
+      def consume_comments str
+        return str unless str.start_with? "("
+        index = 1
+        loop do
+          char = str[index]
+          case char
+          when nil
+            raise ParseError, "Comment never finished"
+          when ")"
+            break
+          when "\\"
+            index += 2
+          when "("
+            str = consume_comments str[index..-1]
+            index = 0
+          else
+            index += 1
+          end
         end
-        params
+        index += 1
+        consume_comments str[index..-1].strip
       end
     end
   end