functions_framework 0.2.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 921150d16d50802b1fa0e5f4f6fb5d3c71aee1dd87e8242ce2e0b63dc8c6320b
-  data.tar.gz: 9b2fd4967811fc1225319102a6aadb56497d90241f6678933843a88299ea926c
+  metadata.gz: 370556a72cd31e4d24499b0715ca7f96a0598cb856fb28fed3d3eaabee0a80ae
+  data.tar.gz: 04a24cf1e2f205fe124eb0bda891f647177b93c43ba1c2286ed52ffbad18cb1d
 SHA512:
-  metadata.gz: 90ea5d1622b446eb02a84a79717c92b47fadc6b5420f153acd48d0b01716a44dd6dc6cbea6851f446fde70e5a53522569b95cde61c5807563dee5b0bc4a6b50c
-  data.tar.gz: 0dd19692bfaa5566c4da5151d78c9d233b9241089d186d5461ef13e83529ca9de7f04e8736fbae70fd361a1fc2b605c03947d23867d28c2c9f80995d9cf60d06
+  metadata.gz: 34d91fa0417632a253ddba1db7aa85f54697eb645caaaf96c9253a36fca241bca80bf17a40796dd5c8521d2c7bbe04ff23353764491d28b5e4335e0ee022f05a
+  data.tar.gz: 0d8d59ef3e45d3980136d7015e8066052bffe3942c442f715368dcf6ac5dd98b0cb282c313fa1a387ac70514747701e75c879c549faa9802444fe6b4d56115c7

data/CHANGELOG.md

@@ -1,8 +1,40 @@
 # Changelog
 
+### v0.5.0 / 2020-07-09
+
+* Removed embedded CloudEvents classes and added the official CloudEvents SDK as a dependency. A `FunctionsFramework::CloudEvents` alias provides backward compatibility.
+
+### 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.
+* 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.2"
+gem "functions_framework", "~> 0.5"
 ```
 
 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.5"
 ```
 
 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/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.5"
+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/cloud_events/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/cloud_events/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.5"
 ```
 
 ```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

@@ -14,7 +14,8 @@
 
 require "logger"
 
-require "functions_framework/cloud_events"
+require "cloud_events"
+
 require "functions_framework/function"
 require "functions_framework/legacy_event_converter"
 require "functions_framework/registry"
@@ -44,10 +45,6 @@ require "functions_framework/version"
 #
 # Here is a roadmap to the internal modules in the Ruby functions framework.
 #
-#  *  {FunctionsFramework::CloudEvents} provides an implementation of the
-#     [CloudEvents](https://cloudevents.io) specification. In particular, if
-#     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-ruby` executable. Most apps will not need to interact
 #     with this class directly.
@@ -94,6 +91,12 @@ module FunctionsFramework
   #
   DEFAULT_SOURCE = "./app.rb".freeze
 
+  ##
+  # The CloudEvents implementation was extracted to become the official
+  # CloudEvents SDK. This alias is left here for backward compatibility.
+  #
+  CloudEvents = ::CloudEvents
+
   class << self
     ##
     # The "global" registry that holds events defined by the
@@ -139,23 +142,13 @@ 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.
     #
     # 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://rubydoc.info/gems/cloud_events/CloudEvents/Event).
+    # Any return value is ignored.
     #
     # ## Example
     #

data/lib/functions_framework/function.rb

@@ -16,21 +16,60 @@ module FunctionsFramework
   ##
   # Representation of a function.
   #
-  # A function has a name, a type, and a code definition.
+  # A function has a name, a type, and an implementation.
+  #
+  # The implementation in general is an object that responds to the `call`
+  # method. For a function of type `:http`, the `call` method takes a single
+  # `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
+  # [CloudEvent](https://rubydoc.info/gems/cloud_events/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
+  # times concurrently in separate threads.
+  #
+  # Alternately, the implementation may be provided as a class that should be
+  # instantiated to produce a callable object. If a class is provided, it should
+  # either subclass {FunctionsFramework::Function::CallBase} or respond to the
+  # same constructor interface, i.e. accepting arbitrary keyword arguments. A
+  # separate callable object will be instantiated from this class for every
+  # function invocation, so each instance will be used for only one invocation.
+  #
+  # Finally, an implementation can be provided as a block. If a block is
+  # provided, it will be recast as a `call` method in an anonymous subclass of
+  # {FunctionsFramework::Function::CallBase}. Thus, providing a block is really
+  # just syntactic sugar for providing a class. (This means, for example, that
+  # the `return` keyword will work within the block because it is treated as a
+  # method.)
   #
   class Function
     ##
     # Create a new function definition.
     #
     # @param name [String] The function name
-    # @param type [Symbol] The type of function. Valid types are
-    #     `:http`, `:event`, and `:cloud_event`.
-    # @param block [Proc] The function code as a proc
+    # @param type [Symbol] The type of function. Valid types are `:http` and
+    #     `:cloud_event`.
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
     #
-    def initialize name, type, &block
+    def initialize name, type, callable = nil, &block
       @name = name
       @type = type
-      @block = block
+      @callable = @callable_class = nil
+      if callable.respond_to? :call
+        @callable = callable
+      elsif callable.is_a? ::Class
+        @callable_class = callable
+      elsif block_given?
+        @callable_class = ::Class.new CallBase do
+          define_method :call, &block
+        end
+      else
+        raise ::ArgumentError, "No callable given for function"
+      end
     end
 
     ##
@@ -44,30 +83,48 @@ module FunctionsFramework
     attr_reader :type
 
     ##
-    # @return [Proc] The function code as a proc
+    # Get a callable for performing a function invocation. This will either
+    # return the singleton callable object, or instantiate a new callable from
+    # the configured class.
     #
-    attr_reader :block
+    # @param logger [::Logger] The logger for use by function executions. This
+    #     may or may not be used by the callable.
+    # @return [#call]
+    #
+    def new_call logger: nil
+      return @callable unless @callable.nil?
+      logger ||= FunctionsFramework.logger
+      @callable_class.new logger: logger, function_name: name, function_type: type
+    end
 
     ##
-    # Call the function. You must pass an argument appropriate to the type
-    # of function.
-    #
-    #  *  A `:http` type function takes a `Rack::Request` argument, and returns
-    #     a Rack response type. See {FunctionsFramework::Registry.add_http}.
-    #  *  A `:cloud_event` type function takes a
-    #     {FunctionsFramework::CloudEvents::Event} argument, and does not
-    #     return a value. See {FunctionsFramework::Registry.add_cloud_event}.
+    # A base class for a callable object that provides calling context.
     #
-    # @param argument [Rack::Request,FunctionsFramework::CloudEvents::Event]
-    # @return [Object]
+    # An object of this class is `self` while a function block is running.
     #
-    def call argument
-      case type
-      when :event
-        block.call argument.data, argument
-      else
-        block.call argument
+    class CallBase
+      ##
+      # Create a callable object with the given context.
+      #
+      # @param context [keywords] A set of context arguments. See {#context} for
+      #     a list of keys that will generally be passed in. However,
+      #     implementations should be prepared to accept any abritrary keys.
+      #
+      def initialize **context
+        @context = context
       end
+
+      ##
+      # A keyed hash of context information. Common context keys include:
+      #
+      #  *  **:logger** (`Logger`) A logger for use by this function call.
+      #  *  **:function_name** (`String`) The name of the running function.
+      #  *  **:function_type** (`Symbol`) The type of the running function,
+      #     either `:http` or `:cloud_event`.
+      #
+      # @return [Hash]
+      #
+      attr_reader :context
     end
   end
 end