functions_framework 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdf75f322fe9e9e78b5e65bfcc9682097606deffb46137d85b6b1cfde68d3ab8
-  data.tar.gz: 54f8e668875607738141963c70b1960da6c06df69083a7ef4357f66889e1a328
+  metadata.gz: 67b0d5e61bb58f49adefbff9794c960438c1577b4e3d54ee5bf072b134834b71
+  data.tar.gz: 9cb295fd8ba39ea9ad5e8eab1c3055eaa18dddef5a1838cc58d7dcdb2d12fc5e
 SHA512:
-  metadata.gz: 3d6fd59bc3730333e91a049d03089169720390f5f9300420449480924800d97da118a87cdae33224644c3550fe78dfee4a07b18e32e534d9bb7645340fbdf4c9
-  data.tar.gz: 897cef8cc366475123250d4c9a7cea0ccd07989c9ebdc0d88d358d996c5fa727aa9bcc5eb46be286d38e72a9d2512adfbaed743975d0300502516db9e3a5fde2
+  metadata.gz: 99e58e1511a97dc9e8643a034bc089f5bb4b71d5f842b507151d8728f058a3763b0f55dcd952ac71f212773e6087cb333fcfebb814a33f57cd2057fde09d6272
+  data.tar.gz: e5afdebdc20c069c247e58196d75787a8c3b3e51924b7714851006ade62dc70bce62cd9e42501528103eb41f3ffc2d6239e9dd8c6650798bdbd1693268fa431a

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+### v0.6.0 / 2020-09-17
+
+* ADDED: You can use the --version flag to print the framework version
+* ADDED: You can use the --verify flag to verify that a given function is defined
+* ADDED: You can now define blocks that are executed at server startup
+
+### 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`.

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.4"
+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/bin/functions-framework

@@ -16,4 +16,4 @@
 
 require "functions_framework/cli"
 
-::FunctionsFramework::CLI.new.parse_args(::ARGV).run
+::FunctionsFramework::CLI.new.parse_args(::ARGV).run.complete

data/bin/functions-framework-ruby

@@ -16,4 +16,4 @@
 
 require "functions_framework/cli"
 
-::FunctionsFramework::CLI.new.parse_args(::ARGV).run
+::FunctionsFramework::CLI.new.parse_args(::ARGV).run.complete

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.4"
+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

@@ -110,9 +110,8 @@ 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 "functions_framework", "~> 0.5"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -158,9 +157,9 @@ end
 ```
 
 The event parameter will be either a
-[CloudEvents V0.3 Event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V0)
+[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://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V1)
+[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
@@ -198,6 +197,68 @@ FunctionsFramework.http "error_reporter" do |request|
 end
 ```
 
+## Shared resources
+
+Generally, functions should be self-contained and stateless, and should not use
+or share any global state in the Ruby VM. This is because serverless runtimes
+may spin up or terminate instances of your app at any time, and because a
+single instance may be running multiple functions at a time in separate threads.
+
+However, it is sometimes useful to share a resource across multiple function
+invocations that run on the same Ruby instance. For example, you might establish
+a single connection to a remote database or other service, and share it across
+function invocations to avoid incurring the overhead of re-establishing it
+for every function invocation.
+
+When using a shared resource, it is important to keep three things in mind:
+
+ 1. **The shared resource should be thread-safe.** This is because serverless
+    runtimes such as Google Cloud Functions may run multiple functions at a time
+    in separate threads.
+
+ 2. **Use `FunctionsFramework.on_startup` to initialize shared resources.**
+    Do not initialize a shared resource at the top level of your app. This is
+    because serverless runtimes may load your files (and thus execute any Ruby
+    code at the top level) in a build/deployment environment that may not be
+    equipped to support the resource. Instead, initialize resources in a
+    `FunctionsFramework.on_startup` block, which the Functions Framework will
+    call only just before starting a server.
+
+    For example:
+
+    ```ruby
+    require "functions_framework"
+
+    # This local variable is lexically shared among all blocks.
+    storage_client = nil
+
+    # Do not create the storage client here. This may run during deployment
+    # when, e.g., your storage credentials are not accessible.
+    #   require "google/cloud/storage"
+    #   storage_client = Google::Cloud::Storage.new # <- may fail
+
+    # Use an on_startup block to initialize the shared client.
+    # This block runs only when the framework is starting an actual server,
+    # and is guaranteed to complete before any functions are executed.
+    FunctionsFramework.on_startup do
+      require "google/cloud/storage"
+      storage_client = Google::Cloud::Storage.new
+    end
+
+    # The storage_client is shared among all function invocations
+    FunctionsFramework.http "storage_example" do |request|
+      bucket = storage_client.bucket "my-bucket"
+      file = bucket.file "path/to/my-file.txt"
+      file.download.to_s
+    end
+    ```
+
+ 3. **There is no guaranteed cleanup hook.** The Functions Framework does not
+    provide a guaranteed way to register a cleanup task. You can register a
+    `Kernel.at_exit` task, but remember that it is possible for the Ruby VM to
+    terminate without calling it. It is strongly recommended that you use
+    resources that do not require "cleanup".
+
 ## Structuring a project
 
 A Functions Framework based "project" or "application" is a typical Ruby
@@ -207,15 +268,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)
@@ -236,7 +296,7 @@ A simple project might look like this:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.4"
+gem "functions_framework", "~> 0.5"
 ```
 
 ```ruby

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
@@ -144,7 +147,8 @@ module FunctionsFramework
     #
     # 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
     #
@@ -161,6 +165,29 @@ module FunctionsFramework
       self
     end
 
+    ##
+    # Define a server startup task. This is useful for initializing shared
+    # resources that should be accessible across all function invocations in
+    # this Ruby VM.
+    #
+    # Startup tasks are run just before a server starts. All startup tasks are
+    # guaranteed to complete before any function executes. However, they are
+    # run only when preparing to run functions. They are not run, for example,
+    # if an app is loaded to verify its integrity during deployment.
+    #
+    # Startup tasks are passed two arguments: the {FunctionsFramework::Function}
+    # identifying the function to execute, and the
+    # {FunctionsFramework::Server::Config} specifying the (frozen) server
+    # configuration. Tasks have no return value.
+    #
+    # @param block [Proc] The startup task
+    # @return [self]
+    #
+    def on_startup &block
+      global_registry.add_startup_task(&block)
+      self
+    end
+
     ##
     # Start the functions framework server in the background. The server will
     # look up the given target function name in the global registry.
@@ -180,6 +207,7 @@ module FunctionsFramework
         raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
       end
       server = Server.new function, &block
+      global_registry.run_startup_tasks server
       server.respond_to_signals
       server.start
     end