functions_framework 0.3.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f82e8f7fb76005b4b61225b3ca02e31e52caecb2742604b88b6b60ced2945d84
-  data.tar.gz: 5f274cc6bdd13c7367d55212d1fb39f26432d8d00a6d607c09543e3818637c49
+  metadata.gz: 780a948604e7295463a6fa73d771a212c0df6f1b49b9e04d75568c499b201c04
+  data.tar.gz: 1e5e02ca296f24a0e86e95b9aaff9b680e687c67cda90199ee6854367752fb63
 SHA512:
-  metadata.gz: 6470be9c192f2231a610830bf51563638ce27e4330f071dd28b41a8fc15811704ace7025cede45ea54a13b4862d86153401360523d6bb479735793e1ed1e00c4
-  data.tar.gz: c7fd524f8c7c4819a6cb6a95d7e7ec0aa371e4211c8b521efe42d63ab3ca794dbfad490613633660c89aaa01479cbfe4d5e98683454e6bd4cdc382f1978da396
+  metadata.gz: f92218000f31d2a60494a2ac2273f20af3bd584da1fa524964e45460a6670686e77eee0bc807e1d9add0d779e842c05ed054d7e89b16cae0a8496557dbd76269
+  data.tar.gz: 93e7e1a801cf4a4c6a32e051d6c39d8e5a70bbfe18aca97838d690faf0e22995c3595b1ea3075a356d4d6a1af267edfff10f424727aa4da1c4cf246b48ec3528

data/CHANGELOG.md

@@ -1,12 +1,44 @@
 # Changelog
 
+### v0.5.1 / 2020-07-20
+
+* Updated some documentation links. No functional changes.
+
+### 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

@@ -1,4 +1,4 @@
-# Functions Framework [![Documentation](https://img.shields.io/badge/docs-FunctionsFramework-red.svg)](https://rubydoc.info/gems/functions_framework/FunctionsFramework) [![Gem Version](https://badge.fury.io/rb/functions_framework.svg)](https://badge.fury.io/rb/functions_framework)
+# Functions Framework [![Documentation](https://img.shields.io/badge/docs-FunctionsFramework-red.svg)](https://googlecloudplatform.github.io/functions-framework-ruby/latest) [![Gem Version](https://badge.fury.io/rb/functions_framework.svg)](https://badge.fury.io/rb/functions_framework)
 
 An open source framework for writing lightweight, portable Ruby functions that
 run in a serverless environment. Functions written to this Framework will run
@@ -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.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!
 ```
 
@@ -98,26 +98,26 @@ Stop the server with `CTRL+C`.
 
 These guides provide additional getting-started information.
 
- *  **[Writing Functions](https://rubydoc.info/gems/functions_framework/file/docs/writing-functions.md)**
+ *  **[Writing Functions](https://googlecloudplatform.github.io/functions-framework-ruby/latest/file.writing-functions.html)**
     : How to write functions that respond to HTTP requests, industry-standard
     [CloudEvents](https://cloudevents.io), as well as events sent from Google
     Cloud services such as [Pub/Sub](https://cloud.google.com/pubsub) and
     [Storage](https://cloud.google.com/storage).
- *  **[Testing Functions](https://rubydoc.info/gems/functions_framework/file/docs/testing-functions.md)**
+ *  **[Testing Functions](https://googlecloudplatform.github.io/functions-framework-ruby/latest/file.testing-functions.html)**
     : How to use the testing features of the Functions Framework to write local
     unit tests for your functions using standard Ruby testing frameworks such
     as [Minitest](https://github.com/seattlerb/minitest) and
     [RSpec](https://rspec.info/).
- *  **[Running a Functions Server](https://rubydoc.info/gems/functions_framework/file/docs/running-a-functions-server.md)**
+ *  **[Running a Functions Server](https://googlecloudplatform.github.io/functions-framework-ruby/latest/file.running-a-functions-server.html)**
     : How to use the `functions-framework-ruby` executable to run a local
     functions server.
- *  **[Deploying Functions](https://rubydoc.info/gems/functions_framework/file/docs/deploying-functions.md)**
+ *  **[Deploying Functions](https://googlecloudplatform.github.io/functions-framework-ruby/latest/file.deploying-functions.html)**
     : How to deploy functions to
     [Google Cloud Functions](https://cloud.google.com/functions) or
     [Google Cloud Run](https://cloud.google.com/run).
 
 The library reference documentation can be found at:
-https://rubydoc.info/gems/functions_framework
+https://googlecloudplatform.github.io/functions-framework-ruby
 
 Additional examples are available in the `examples` directory:
 https://github.com/GoogleCloudPlatform/functions-framework-ruby/blob/master/examples/

data/docs/deploying-functions.md

@@ -105,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:
@@ -165,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.3"
+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!
 ```
 
@@ -121,7 +121,7 @@ These guides provide additional getting-started information.
     [Google Cloud Run](https://cloud.google.com/run).
 
 The library reference documentation can be found at:
-https://rubydoc.info/gems/functions_framework
+https://googlecloudplatform.github.io/functions-framework-ruby
 
 Additional examples are available in the GitHub repository:
 https://github.com/GoogleCloudPlatform/functions-framework-ruby/blob/master/examples/

data/docs/testing-functions.md

@@ -17,9 +17,8 @@ the output. You do not need to set up (or mock) an actual server.
 The Functions Framework provides utility methods that streamline the process of
 setting up functions and the environment for testing, constructing input
 parameters, and interpreting results. These are available in the
-[Testing module](https://rubydoc.info/gems/functions_framework/FunctionsFramework/Testing).
-Generally, you can include this module in your Minitest test class or RSpec
-describe block.
+{FunctionsFramework::Testing} module. Generally, you can include this module in
+your Minitest test class or RSpec describe block.
 
 ```ruby
 require "minitest/autorun"
@@ -45,10 +44,10 @@ end
 
 To test a function, you'll need to load the Ruby file that defines the function,
 and run the function to test its results. The Testing module provides a method
-[load_temporary](https://rubydoc.info/gems/functions_framework/FunctionsFramework/Testing#load_temporary-instance_method),
-which loads a Ruby file, defining functions but only for the scope of your test.
-This allows your test to coexist with tests for other functions, even functions
-with the same name from a different Ruby file.
+{FunctionsFramework::Testing#load_temporary}, which loads a Ruby file, defining
+functions but only for the scope of your test. This allows your test to coexist
+with tests for other functions, even functions with the same name from a
+different Ruby file.
 
 ```ruby
 require "minitest/autorun"
@@ -91,8 +90,8 @@ includes helper methods that you can use to create simple requests for many
 basic cases.
 
 When you have constructed an input request, use
-[call_http](https://rubydoc.info/gems/functions_framework/FunctionsFramework/Testing#call_http-instance_method)
-to call a named function, passing the request object. This method returns a
+{FunctionsFramework::Testing#call_http} to call a named function, passing the
+request object. This method returns a
 [Rack::Response](https://rubydoc.info/gems/rack/Rack/Response) that you can
 assert against.
 
@@ -142,8 +141,7 @@ end
 
 Testing a CloudEvent function works similarly. The `Testing` module provides
 methods to help construct example CloudEvent objects, which can then be passed
-to the method
-[call_event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/Testing#call_event-instance_method).
+to the method {FunctionsFramework::Testing#call_event}.
 
 Unlike HTTP functions, event functions do not have a return value. Instead, you
 will need to test side effects. A common approach is to test logs by capturing

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://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V0)
+object ([see spec](https://github.com/cloudevents/spec/blob/v0.3/spec.md)) or a
+[CloudEvents V1.0 Event](https://cloudevents.github.io/sdk-ruby/latest/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.5"
 ```
 
 ```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

@@ -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://cloudevents.github.io/sdk-ruby/latest/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://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
+  # 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