functions_framework 0.3.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d09fadc9facfc650793e4c6c30f8dab5f2e5909d0d068d18e0da0bd8a748115d
-  data.tar.gz: 7b99ab480e94f1ed4eae784121030a07106451cdc1ddd0de5e5b1d7edabbe41f
+  metadata.gz: 5e8f0eda1f51ead6ec3bd53d711d2a7816b5077351f56bfa491311c73461a02d
+  data.tar.gz: 21921bddd89a66dc95245850cb475967fd5e8de7c678bf4e154d07d7a8264290
 SHA512:
-  metadata.gz: b4cc30e0acb40f3de6e9a412b240c2f910a539d9b9e76085bcb701d605f657b5239b4bbeabf9a7f5e78c220ff4931ae34c7f21d028d4e472874308c91d26d997
-  data.tar.gz: d059a1fc586dfb12bbd06a757abf46227f0dcfc54c8653365198b596045a0c34d3fd4d00fcddc331a19d5bb028f5e52f5684aa022136b1258ce59a31ec195bd2
+  metadata.gz: '08633f2559e4d787f23e2711d40ff17437e74cd9ee4589346bd3c4f567815c422cb6e2827125bad2de5d23f4e52c3a09162db609a4fd62aee4374144ae16686e'
+  data.tar.gz: 759e2fe6a395fe1ea53ba90bbf5026635429fbdacf161b3f87879d31753532b7ef005fbfce797c6ca599bca441f1919b4d61a508cf43877fee18090a4e8f9fec

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+### v0.5.2 / 2020-09-06
+
+* FIXED: Use global $stderr rather than STDERR for logger 
+* DOCS: Fix instructions for deployment to Google Cloud Functions 
+
+### 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.
@@ -12,7 +43,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

@@ -1,11 +1,11 @@
-# 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
 in many different environments, including:
 
- *  [Google Cloud Functions](https://cloud.google.com/functions) *(in preview)*
- *  [Cloud Run or Cloud Run for Anthos](https://cloud.google.com/run)
+ *  [Google Cloud Functions](https://cloud.google.com/functions) *(alpha)*
+ *  [Google Cloud Run](https://cloud.google.com/run)
  *  Any other [Knative](https://github.com/knative)-based environment
  *  Your local development machine
 
@@ -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
@@ -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

@@ -34,7 +34,7 @@ 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.
+> **Note:** Ruby support on Cloud Functions is currently in limited alpha.
 > It is not yet suitable for production workloads, and support is best-effort
 > only. Access is currently limited to selected early-access users.
 
@@ -46,30 +46,39 @@ is to `bundle install` or `bundle update` and run your local tests prior to
 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
-the name you provide when writing your function; Cloud Functions calls that name
-the "function target".)
+Also, make sure your source file (which defines your function) is called
+`app.rb`. The Functions Framework lets you choose a function source file, but
+Cloud Functions currently requires you to use `app.rb`.
+
+Decide _which_ function in the source file to invoke, that is, the name that you
+used when writing the function. This is called the **target**. (Note that if you
+did not specify a name for the function, it defaults to the name `function`.)
+
+Choose a Cloud Functions **name** for your function. The **name** identifies
+this function deployment (e.g. in the cloud console) and is also part of the
+function's default URL. (Note: the **name** and the **target** do not have to
+be the same value.)
 
 Then, issue the gcloud command to deploy:
 
 ```sh
-gcloud functions deploy $YOUR_FUNCTION_NAME --project=$YOUR_PROJECT_ID \
-  --runtime=ruby26 --trigger-http --source=$YOUR_FUNCTION_SOURCE \
-  --entry-point=$YOUR_FUNCTION_TARGET
+gcloud functions deploy $YOUR_FUNCTION_NAME \
+    --project=$YOUR_PROJECT_ID \
+    --runtime=ruby26 \
+    --trigger-http \
+    --entry-point=$YOUR_FUNCTION_TARGET
 ```
 
-The source file defaults to `./app.rb` and the function target defaults to
-`function`, so those flags can be omitted if you're using the defaults. The
-project flag can also be omitted if you've set it as the default with
-`gcloud config set project`.
+The `--entry-point=` flag can be omitted if the **target** has the same value
+as the **name**. Additionally, the `--project` flag can be omitted if you've
+set your default project using `gcloud config set project`.
 
 If your function handles events rather than HTTP requests, you'll need to
 replace `--trigger-http` with a different trigger. For details, see the
 [reference documentation](https://cloud.google.com/sdk/gcloud/reference/functions/deploy)
 for `gcloud functions deploy`.
 
-To update your deployment, just redeploy using the same function name.
+To update your deployment, just redeploy using the same function **name**.
 
 ### Configuring Cloud Functions deployments
 
@@ -105,6 +114,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 +180,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

@@ -8,8 +8,8 @@ The Functions Framework is an open source framework for writing lightweight,
 portable Ruby functions that run in a serverless environment. Functions written
 to this Framework will run in many different environments, including:
 
- *  [Google Cloud Functions](https://cloud.google.com/functions) *(in preview)*
- *  [Cloud Run or Cloud Run for Anthos](https://cloud.google.com/run)
+ *  [Google Cloud Functions](https://cloud.google.com/functions) *(alpha)*
+ *  [Google Cloud Run](https://cloud.google.com/run)
  *  Any other [Knative](https://github.com/knative)-based environment
  *  Your local development machine
 
@@ -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
@@ -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
@@ -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,18 @@ 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
+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 +151,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 +188,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
@@ -193,15 +206,14 @@ 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
-good practice to create a separate Ruby file per function.
-
-By convention, the source file is often called `app.rb`, but you can give it
-any name. Projects can also have multiple source files that apply to different
-cases.
+By convention, the "main" Ruby file that defines functions should be called
+`app.rb` and be located at the root of the project. The path to this file is
+sometimes known as the **function source**. The Functions Framework allows you
+to specify an arbitrary source, but suome hosting environments (such as Google
+Cloud Functions) require it to be `./app.rb`.
 
-A simple project might look like this:
+A source file can define any number of functions (with distinct names). Each of
+the names is known as a **function target**.
 
 ```
 (project directory)
@@ -222,7 +234,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 +242,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 +250,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.
@@ -74,7 +71,7 @@ require "functions_framework/version"
 #
 module FunctionsFramework
   @global_registry = Registry.new
-  @logger = ::Logger.new ::STDERR
+  @logger = ::Logger.new $stderr
   @logger.level = ::Logger::INFO
 
   ##
@@ -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
     #