functions_framework 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d09fadc9facfc650793e4c6c30f8dab5f2e5909d0d068d18e0da0bd8a748115d
-  data.tar.gz: 7b99ab480e94f1ed4eae784121030a07106451cdc1ddd0de5e5b1d7edabbe41f
+  metadata.gz: cdf75f322fe9e9e78b5e65bfcc9682097606deffb46137d85b6b1cfde68d3ab8
+  data.tar.gz: 54f8e668875607738141963c70b1960da6c06df69083a7ef4357f66889e1a328
 SHA512:
-  metadata.gz: b4cc30e0acb40f3de6e9a412b240c2f910a539d9b9e76085bcb701d605f657b5239b4bbeabf9a7f5e78c220ff4931ae34c7f21d028d4e472874308c91d26d997
-  data.tar.gz: d059a1fc586dfb12bbd06a757abf46227f0dcfc54c8653365198b596045a0c34d3fd4d00fcddc331a19d5bb028f5e52f5684aa022136b1258ce59a31ec195bd2
+  metadata.gz: 3d6fd59bc3730333e91a049d03089169720390f5f9300420449480924800d97da118a87cdae33224644c3550fe78dfee4a07b18e32e534d9bb7645340fbdf4c9
+  data.tar.gz: 897cef8cc366475123250d4c9a7cea0ccd07989c9ebdc0d88d358d996c5fa727aa9bcc5eb46be286d38e72a9d2512adfbaed743975d0300502516db9e3a5fde2

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+### v0.4.0 / 2020-06-29
+
+* Dropped the legacy and largely unsupported `:event` function type. All event functions should be of type `:cloud_event`.
+* Define the object context for function execution, and include an extensible context helper.
+* Support for CloudEvents with specversion 0.3.
+* CloudEvents now correct percent-encodes/decodes binary headers.
+* CloudEvents now includes more robust RFC 2045 parsing of the Content-Type header.
+* The CloudEventsError class now properly subclasses StandardError instead of RuntimeError.
+* Removed redundant `_string` accessors from event classes since raw forms are already available via `[]`.
+* A variety of corrections to event-related class documentation.
+
 ### v0.3.1 / 2020-06-27
 
 * Fixed crash when using "return" directly in a function block.
@@ -12,7 +23,7 @@
 
 ### v0.2.1 / 2020-06-25
 
-* The `--signature-type` check recognizes the legacy `event` type.
+* The `--signature-type` check recognizes the legacy `event` type for `:cloud_event` functions.
 
 ### v0.2.0 / 2020-06-24
 

data/README.md

@@ -60,7 +60,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.3"
+gem "functions_framework", "~> 0.4"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/docs/overview.md

@@ -64,7 +64,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.3"
+gem "functions_framework", "~> 0.4"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/docs/writing-functions.md

@@ -30,7 +30,7 @@ that returns a simple message in the HTTP response body:
 ```ruby
 require "functions_framework"
 
-FunctionsFramework.http("hello") do |request|
+FunctionsFramework.http "hello" do |request|
   # Return the response body.
   "Hello, world!\n"
 end
@@ -51,7 +51,7 @@ request information in the response:
 ```ruby
 require "functions_framework"
 
-FunctionsFramework.http("request_info") do |request|
+FunctionsFramework.http "request_info_example" do |request|
   # Include some request info in the response body.
   "Received #{request.method} from #{request.url}!\n"
 end
@@ -66,7 +66,7 @@ hosting environment.
 ```ruby
 require "functions_framework"
 
-FunctionsFramework.http("logging_example") do |request|
+FunctionsFramework.http "logging_example" do |request|
   # Log some request info.
   request.logger.info "I received #{request.method} from #{request.url}!"
   # A simple response body.
@@ -106,10 +106,19 @@ framework such as Ruby on Rails, you may want to consider a solution such as
 Google Cloud Run that is tailored to larger applications. However, a lightweight
 framework such as Sinatra is sometimes useful when writing HTTP functions.
 
-It is easy to connect an HTTP function to a Sinatra app. Write the Sinatra app
-using the "modular" Sinatra interface (i.e. subclass `Sinatra::Base`), and then
-simply run the Sinatra app as a Rack handler from the function. Here is a basic
-example:
+It is easy to connect an HTTP function to a Sinatra app. First, declare the
+dependency on Sinatra in your `Gemfile`:
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "functions_framework", "~> 0.4"
+gem "sinatra", "~> 2.0"
+```
+
+Write the Sinatra app using the "modular" Sinatra interface (i.e. subclass
+`Sinatra::Base`), and then run the Sinatra app directly as a Rack handler from
+the function. Here is a basic example:
 
 ```ruby
 require "functions_framework"
@@ -143,20 +152,25 @@ information about it:
 ```ruby
 require "functions_framework"
 
-FunctionsFramework.cloud_event("hello") do |event|
+FunctionsFramework.cloud_event "hello" do |event|
   FunctionsFramework.logger.info "I received an event of type #{event.type}!"
 end
 ```
 
-The event parameter is a
-[CloudEvents V1 Event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V1)
-object. You can find detailed information about the fields of a CloudEvent from
-the [CloudEvents spec](https://github.com/cloudevents/spec/blob/v1.0/spec.md).
+The event parameter will be either a
+[CloudEvents V0.3 Event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V0)
+object ([see spec](https://github.com/cloudevents/spec/blob/v0.3/spec.md)) or a
+[CloudEvents V1.0 Event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V1)
+object ([see spec](https://github.com/cloudevents/spec/blob/v1.0/spec.md)).
 
 Some Google Cloud services send events in a legacy event format that was defined
 prior to CloudEvents. The Functions Framework will convert these legacy events
-to an equivalent CloudEvents type, so your function will always receive a
-CloudEvent object when it is sent an event from Google Cloud.
+to an equivalent CloudEvents V1 type, so your function will always receive a
+CloudEvent object when it is sent an event from Google Cloud. The precise
+mapping between legacy events and CloudEvents is not specified in detail here,
+but in general, the _data_ from the legacy event will be mapped to the `data`
+field in the CloudEvent, and the _context_ from the legacy event will be mapped
+to equivalent CloudEvent attributes.
 
 ## Error handling
 
@@ -175,7 +189,7 @@ HTTP response yourself. For example:
 ```ruby
 require "functions_framework"
 
-FunctionsFramework.http("error_reporter") do |request|
+FunctionsFramework.http "error_reporter" do |request|
   begin
     raise "whoops!"
   rescue RuntimeError => e
@@ -222,7 +236,7 @@ A simple project might look like this:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.3"
+gem "functions_framework", "~> 0.4"
 ```
 
 ```ruby
@@ -230,7 +244,7 @@ gem "functions_framework", "~> 0.3"
 require "functions_framework"
 require_relative "lib/hello"
 
-FunctionsFramework.http("hello") do |request|
+FunctionsFramework.http "hello" do |request|
   Hello.new(request).build_response
 end
 ```
@@ -238,7 +252,7 @@ end
 ```ruby
 # lib/hello.rb
 class Hello
-  def initialize(request)
+  def initialize request
     @request = request
   end
 

data/lib/functions_framework.rb

@@ -139,17 +139,6 @@ module FunctionsFramework
       self
     end
 
-    ##
-    # This is an obsolete interface that defines an event function taking two
-    # arguments (data and context) rather than one.
-    #
-    # @deprecated Use {FunctionsFramework.cloud_event} instead.
-    #
-    def event name = DEFAULT_TARGET, &block
-      global_registry.add_event name, &block
-      self
-    end
-
     ##
     # Define a function that responds to CloudEvents.
     #

data/lib/functions_framework/cloud_events.rb

@@ -23,11 +23,13 @@ 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).
+  # 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
     # @private
-    SUPPORTED_SPEC_VERSIONS = ["1.0"].freeze
+    SUPPORTED_SPEC_VERSIONS = ["0.3", "1.0"].freeze
 
     class << self
       ##

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

data/lib/functions_framework/cloud_events/errors.rb

@@ -17,7 +17,7 @@ module FunctionsFramework
     ##
     # Base class for all CloudEvents errors.
     #
-    class CloudEventsError < ::RuntimeError
+    class CloudEventsError < ::StandardError
     end
 
     ##

data/lib/functions_framework/cloud_events/event.rb

@@ -15,15 +15,15 @@
 require "date"
 require "uri"
 
+require "functions_framework/cloud_events/event/field_interpreter"
+require "functions_framework/cloud_events/event/v0"
 require "functions_framework/cloud_events/event/v1"
 
 module FunctionsFramework
   module CloudEvents
     ##
-    # CloudEvent object.
-    #
-    # An Event object represents a complete event, including both its data and
-    # its context attributes. The following are true of all event objects:
+    # An Event object represents a complete CloudEvent, including both data and
+    # context attributes. The following are true of all event objects:
     #
     #  *  Event classes are defined within this module. For example, events
     #     conforming to the CloudEvents 1.0 specification are of type
@@ -49,8 +49,11 @@ module FunctionsFramework
     #     {CloudEvents::JsonFormat} to decode an event from JSON, or use
     #     {CloudEvents::HttpBinding} to decode an event from an HTTP request.
     #
-    # See https://github.com/cloudevents/spec/blob/master/spec.md for more
-    # information about CloudEvents.
+    # See https://github.com/cloudevents/spec for more information about
+    # CloudEvents. The documentation for the individual event classes
+    # {FunctionsFramework::CloudEvents::Event::V0} and
+    # {FunctionsFramework::CloudEvents::Event::V1} also include links to their
+    # respective specifications.
     #
     module Event
       class << self
@@ -66,6 +69,8 @@ module FunctionsFramework
         #
         def create spec_version:, **kwargs
           case spec_version
+          when "0.3"
+            V0.new spec_version: spec_version, **kwargs
           when /^1(\.|$)/
             V1.new spec_version: spec_version, **kwargs
           else