functions_framework 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3591e5ab03b6e29d0a7f9b9c16d4d470138fbf0ddebec875e80f5f1df8a9767
-  data.tar.gz: 50ed98f079c42638fcb3328bab3d1388e323613ea310842bcd3d887b1a96fdfb
+  metadata.gz: 817129c1773079fed039152996a18e91a054241940b8d6e3437cb66e10046304
+  data.tar.gz: ff3f61597726b60241e8b528ef520641fa3f08ddb7adcdfb32f9413fcb125f45
 SHA512:
-  metadata.gz: 87a9631c32f05b5e5831f50e9dd7235351fd6556fb22474d655a916ceacf1d57e1d25a60369c31aa3790a9667cafec02dafad2ccf9c98499a681badf2516d13e
-  data.tar.gz: 755d890b0684d2af126306c3b7f7f2e5d3b1392b0fb88e325b45eba6c85d9d6cc28e320e20a8a9d716244e52e63fee839ab02ec56014873c62dd77f3fe4ea37c
+  metadata.gz: 7396117d6e94bec87c70c697c7364b9256c7575f61c7259eb25df65694e9627b6c33a93e0caaea5d9d7955707e731eaddc27b90d4595f0029d181fc6cc18bfdf
+  data.tar.gz: 8eb929ace2a49ae764f5de0fef6dd7e0d668c80864368ad2379d0e52a89a44c7a3514e92dc02802d940374808a271a89f3076f1c8f3d0a532204118615e0c1af

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+### v0.4.1 / 2020-07-08
+
+* Fixed unsupported signal error on Windows.
+* Fixed several edge case errors in legacy event conversion.
+* Generated Content-Type headers now properly quote param values if needed.
+* Minor documentation updates.
+
+### 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.
+* Added a more flexible request generation helper in the testing module.
+* Fixed several typos in the documentation.
+
+### v0.3.0 / 2020-06-26
+
+* Updated the CloudEvent data format for converted pubsub events to conform to Cloud Run's conversion.
+
+### v0.2.1 / 2020-06-25
+
+* The `--signature-type` check recognizes the legacy `event` type for `:cloud_event` functions.
+
 ### v0.2.0 / 2020-06-24
 
 Significant changes:

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.2"
+gem "functions_framework", "~> 0.4"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a
@@ -88,7 +88,7 @@ bundle exec functions-framework-ruby --target hello
 In a separate shell, you can send requests to this function using curl:
 
 ```sh
-curl https://localhost:8080
+curl http://localhost:8080
 # Output: Hello, world!
 ```
 

data/docs/deploying-functions.md

@@ -30,12 +30,21 @@ Google Cloud Functions is Google's scalable pay-as-you-go Functions-as-a-Service
 Functions Framework is designed especially for functions that can be hosted on
 Cloud Functions.
 
+You can run Ruby functions on Google Cloud Functions by selecting the `ruby26`
+runtime. This runtime uses a recent release of Ruby 2.6. Support for other
+versions of Ruby may be added in the future.
+
+> **Note:** Ruby support on Cloud Functions is currently in limited preview.
+> It is not yet suitable for production workloads, and support is best-effort
+> only. Access is currently limited to selected early-access users.
+
 ### Deploying and updating your function
 
 Before you can deploy to Cloud Functions, make sure your bundle, and in
 particular your `Gemfile.lock` file, is up to date. The easiest way to do this
 is to `bundle install` or `bundle update` and run your local tests prior to
-deploying.
+deploying. Cloud Functions will not accept your function unless an up-to-date
+`Gemfile.lock` is present.
 
 Choose a name for your function. This function name is how it will appear in the
 cloud console, and will also be part of the function's URL. (It's different from
@@ -96,6 +105,12 @@ to adapt it if you have an Anthos installation.
 
 ### Building an image for your function
 
+Before you can deploy to Cloud Run, make sure your bundle, and in
+particular your `Gemfile.lock` file, is up to date. The easiest way to do this
+is to `bundle install` or `bundle update` and run your local tests prior to
+deploying. The configuration used in the Dockerfile below will not accept your
+function unless an up-to-date `Gemfile.lock` is present.
+
 First, build a Docker image containing your function. Following is a simple
 Dockerfile that you can use as a starting point. Feel free to adjust it to the
 needs of your project:
@@ -126,6 +141,10 @@ You must use your project ID, but you can choose an app name and build ID. The
 command may ask you for permission to enable the Cloud Build API for the project
 if it isn't already enabled.
 
+Because you provide your own Docker image when deploying to Cloud Run, you can
+use any version of Ruby supported by the Functions Framework, from 2.4 through
+2.7.
+
 ### Deploying an image to Cloud Run
 
 To deploy to Cloud Run, specify the same image URL that you built above. For
@@ -152,7 +171,7 @@ deployed function.
 
 Note that our Dockerfile's entrypoint did not pass any source file or target
 name to the Functions Framework. If these are not specified, the Framework will
-use the source `.app.rb` and the target `function` by default. To use different
+use the source `./app.rb` and the target `function` by default. To use different
 values, you need to set the appropriate environment variables when deploying, as
 illustrated above with the `FUNCTION_SOURCE` and `FUNCTION_TARGET` variables.
 

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.2"
+gem "functions_framework", "~> 0.4"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a
@@ -92,7 +92,7 @@ bundle exec functions-framework-ruby --target hello
 In a separate shell, you can send requests to this function using curl:
 
 ```sh
-curl https://localhost:8080
+curl http://localhost:8080
 # Output: Hello, world!
 ```
 

data/docs/running-a-functions-server.md

@@ -101,7 +101,7 @@ Command-line flag   | Environment variable       | Description
 `--port`            | `PORT`                     | The port on which the Functions Framework listens for requests. Default: `8080`.
 `--target`          | `FUNCTION_TARGET`          | The name of the exported function to be invoked in response to requests. Default: `function`.
 `--source`          | `FUNCTION_SOURCE`          | The path to the file containing your function. Default: `app.rb` (in the current working directory).
-`--signature-type`  | `FUNCTION_SIGNATURE_TYPE`  | Verifies that the function has the expected signature. Allowed values: `http` or `cloudevent`.
+`--signature-type`  | `FUNCTION_SIGNATURE_TYPE`  | Verifies that the function has the expected signature. Allowed values: `http`, `event`, or `cloudevent`.
 `--environment`     | `RACK_ENV`                 | Sets the Rack environment.
 `--bind`            | `FUNCTION_BIND_ADDR`       | Binds to the given address. Default: `0.0.0.0`.
 `--min-threads`     | `FUNCTION_MIN_THREADS`     | Sets the minimum thread pool size, overriding Puma's default.

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
@@ -43,7 +43,7 @@ now cover these in a bit more detail.
 
 An HTTP function is passed a request, which is an object of type
 [Rack::Request](https://rubydoc.info/gems/rack/Rack/Request). This object
-provides methods methods for obtaining request information such as the method,
+provides methods for obtaining request information such as the method,
 path, query parameters, body content, and headers. You can also obtain the raw
 Rack environment using the `env` method. The following example includes some
 request information in the response:
@@ -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 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
@@ -188,9 +202,10 @@ end
 
 A Functions Framework based "project" or "application" is a typical Ruby
 application. It should include a `Gemfile` that specifies the gem dependencies
-(including the `functions_framework` gem itself), and at least one Ruby source
-file that defines functions. It can also include additional Ruby files defining
-classes and methods that assist in the function implementation.
+(including the `functions_framework` gem itself), and any other dependencies
+needed by the function. It must include at least one Ruby source file that
+defines functions, and can also include additional Ruby files defining classes
+and methods that assist in the function implementation.
 
 The "entrypoint" to the project, also called the "source", is a Ruby file. It
 can define any number of functions (with distinct names), although it is often
@@ -221,7 +236,7 @@ A simple project might look like this:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.2"
+gem "functions_framework", "~> 0.4"
 ```
 
 ```ruby
@@ -229,7 +244,7 @@ gem "functions_framework", "~> 0.2"
 require "functions_framework"
 require_relative "lib/hello"
 
-FunctionsFramework.http("hello") do |request|
+FunctionsFramework.http "hello" do |request|
   Hello.new(request).build_response
 end
 ```
@@ -237,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/cli.rb

@@ -137,7 +137,7 @@ module FunctionsFramework
       raise "Undefined function: #{@target.inspect}" if function.nil?
       unless @signature_type.nil? ||
              @signature_type == "http" && function.type == :http ||
-             @signature_type == "cloudevent" && function.type == :cloud_event
+             ["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|

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
+                            @params.map { |k, v| "; #{k}=#{maybe_quote 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,96 @@ 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
+      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
-        params.sort! do |(k1, v1), (k2, v2)|
-          a = k1 <=> k2
-          a.zero? ? v1 <=> v2 : a
+        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
+
+      def maybe_quote str
+        return str if /^[\w!#\$%&'\*\+\.\^`\{\|\}-]+$/ =~ str
+        str = str.gsub("\\", "\\\\\\\\").gsub("\"", "\\\\\"")
+        "\"#{str}\""
       end
     end
   end