functions_framework 0.5.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e8f0eda1f51ead6ec3bd53d711d2a7816b5077351f56bfa491311c73461a02d
-  data.tar.gz: 21921bddd89a66dc95245850cb475967fd5e8de7c678bf4e154d07d7a8264290
+  metadata.gz: 6a4d1e19c5565de4604964e48ff818b05460b2211ef2c8cfbd100bd572d802d7
+  data.tar.gz: 380d987acf157075cfe7fca5bf038404eb800f48b80614ce9781f44cbd6de764
 SHA512:
-  metadata.gz: '08633f2559e4d787f23e2711d40ff17437e74cd9ee4589346bd3c4f567815c422cb6e2827125bad2de5d23f4e52c3a09162db609a4fd62aee4374144ae16686e'
-  data.tar.gz: 759e2fe6a395fe1ea53ba90bbf5026635429fbdacf161b3f87879d31753532b7ef005fbfce797c6ca599bca441f1919b4d61a508cf43877fee18090a4e8f9fec
+  metadata.gz: c76cb765863334411e7ab3bd448912fabc14c7725ae66465426ee996b05557d44653f64d47c98eb429d077f0df558b550b228a3fce014dd5aa9e02e4933cbc62
+  data.tar.gz: af8d74d419c75dc8f850fa989d48780a26e2639045ff945d4b0a1cd29fa0085d3a82d058db6e49ed9c9f2c2855b3bc495a44ab530e129a846b24c111c76f79f2

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+### v0.9.0 / 2021-03-18
+
+* BREAKING CHANGE: Servers are configured as single-threaded in production by default, matching the current behavior of Google Cloud Functions.
+* FIXED: Fixed conversion of Firebase events to CloudEvents to conform to the specs used by Cloud Functions and Cloud Run.
+* FIXED: Fixed an error when reading a global set to a Minitest::Mock. This will make it easier to write tests that use mocks for global resources.
+
+### v0.8.0 / 2021-03-02
+
+* ADDED: Support for lazily-initialized globals
+
+### v0.7.1 / 2021-01-26
+
+* DOCS: Fixed several errors in the writing-functions doc samples
+* DOCS: Updated documentation to note public release of GCF support 
+
+### v0.7.0 / 2020-09-25
+
+* Now requires Ruby 2.5 or later.
+* BREAKING CHANGE: Renamed "context" hash to "globals" and made it read-only for normal functions.
+* BREAKING CHANGE: Server config is no longer passed to startup blocks.
+* ADDED: Provided a "logger" convenience method in the context object.
+* ADDED: Globals can be set from startup blocks, which is useful for initializing shared resources.
+* ADDED: Support for testing startup tasks in the Testing module.
+* ADDED: Support for controlling logging in the Testing module.
+* FIXED: Fixed crash introduced in 0.6.0 when a block didn't declare an expected argument.
+* FIXED: Better support for running concurrent tests.
+* DOCS: Expanded documentation on initialization, execution context, and shared resources.
+* DEPRECATED: The functions-framework executable is deprecated. Use functions-framework-ruby instead.
+
+### 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 

data/README.md

@@ -1,10 +1,10 @@
-# 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)
+# Functions Framework for Ruby [![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) *(alpha)*
+ *  [Google Cloud Functions](https://cloud.google.com/functions) *(public preview)*
  *  [Google Cloud Run](https://cloud.google.com/run)
  *  Any other [Knative](https://github.com/knative)-based environment
  *  Your local development machine
@@ -42,11 +42,11 @@ requiring an HTTP server or complicated request handling logic.
 
 ## Supported Ruby versions
 
-This library is supported on Ruby 2.4+.
+This library is supported on Ruby 2.5+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.4
+in security maintenance, and not end of life. Currently, this means Ruby 2.5
 and later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
@@ -60,7 +60,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.9"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/bin/functions-framework

@@ -16,4 +16,7 @@
 
 require "functions_framework/cli"
 
-::FunctionsFramework::CLI.new.parse_args(::ARGV).run
+puts "WARNING: The functions-framework executable is deprecated and will be"
+puts "removed in a future version. Please use functions-framework-ruby instead."
+
+::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

@@ -31,12 +31,8 @@ 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 alpha.
-> It is not yet suitable for production workloads, and support is best-effort
-> only. Access is currently limited to selected early-access users.
+runtime or `ruby27` runtime to use a recent release of Ruby 2.6 or Ruby 2.7.
+Support for Ruby 3.0 is forthcoming.
 
 ### Deploying and updating your function
 
@@ -64,7 +60,7 @@ Then, issue the gcloud command to deploy:
 ```sh
 gcloud functions deploy $YOUR_FUNCTION_NAME \
     --project=$YOUR_PROJECT_ID \
-    --runtime=ruby26 \
+    --runtime=ruby27 \
     --trigger-http \
     --entry-point=$YOUR_FUNCTION_TARGET
 ```
@@ -90,7 +86,7 @@ and above, set `FUNCTION_LOGGING_LEVEL` to `WARN` when deploying:
 
 ```sh
 gcloud functions deploy $YOUR_FUNCTION_NAME --project=$YOUR_PROJECT_ID \
-  --runtime=ruby26 --trigger-http --source=$YOUR_FUNCTION_SOURCE \
+  --runtime=ruby27 --trigger-http --source=$YOUR_FUNCTION_SOURCE \
   --entry-point=$YOUR_FUNCTION_TARGET \
   --set-env-vars=FUNCTION_LOGGING_LEVEL=WARN
 ```
@@ -125,7 +121,7 @@ Dockerfile that you can use as a starting point. Feel free to adjust it to the
 needs of your project:
 
 ```
-FROM ruby:2.6
+FROM ruby:2.7
 WORKDIR /app
 COPY . .
 RUN gem install --no-document bundler \
@@ -151,8 +147,8 @@ 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.
+use any version of Ruby supported by the Functions Framework, from 2.5 through
+3.0.
 
 ### Deploying an image to Cloud Run
 

data/docs/overview.md

@@ -8,7 +8,7 @@ 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) *(alpha)*
+ *  [Google Cloud Functions](https://cloud.google.com/functions) *(public preview)*
  *  [Google Cloud Run](https://cloud.google.com/run)
  *  Any other [Knative](https://github.com/knative)-based environment
  *  Your local development machine
@@ -46,11 +46,11 @@ requiring an HTTP server or complicated request handling logic.
 
 ## Supported Ruby versions
 
-This library is supported on Ruby 2.4+.
+This library is supported on Ruby 2.5+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.4
+in security maintenance, and not end of life. Currently, this means Ruby 2.5
 and later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
@@ -64,7 +64,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.9"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/docs/testing-functions.md

@@ -165,3 +165,53 @@ class MyTest < Minitest::Test
   end
 end
 ```
+
+## Testing startup tasks
+
+When a functions server is starting up, it calls startup tasks automatically.
+In the testing environment, when you call a function using the
+{FunctionsFramework::Testing#call_http} or
+{FunctionsFramework::Testing#call_event} methods, the testing environment will
+also automatically execute any startup tasks for you.
+
+You can also call startup tasks explicitly to test them in isolation, using the
+{FunctionsFramework::Testing#run_startup_tasks} method. Pass the name of a
+function, and the testing module will execute all defined startup blocks, in
+order, as if the server were preparing that function for execution.
+{FunctionsFramework::Testing#run_startup_tasks} returns the resulting globals
+as a hash, so you can assert against its contents.
+
+If you use {FunctionsFramework::Testing#run_startup_tasks} to run the startup
+tasks explicitly, they will not be run again when you call the function itself
+using {FunctionsFramework::Testing#call_http} or
+{FunctionsFramework::Testing#call_event}. However, if startup tasks have
+already been run implicitly by {FunctionsFramework::Testing#call_http} or
+{FunctionsFramework::Testing#call_event}, then attempting to run them again
+explicitly by calling {FunctionsFramework::Testing#run_startup_tasks} will
+result in an exception.
+
+There is currently no way to run a single startup block in isolation. If you
+have multiple startup blocks defined, they are always executed together.
+
+Following is an example test that runs startup tasks explicitly and asserts
+against the effect on the globals.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+
+  def test_startup_tasks
+    load_temporary "app.rb" do
+      globals = run_startup_tasks "my_function"
+      assert_equal "foo", globals[:my_global]
+
+      request = make_get_request "https://example.com/foo"
+      response = call_http "my_function", request
+      assert_equal 200, response.status
+    end
+  end
+end
+```

data/docs/writing-functions.md

@@ -53,7 +53,7 @@ require "functions_framework"
 
 FunctionsFramework.http "request_info_example" do |request|
   # Include some request info in the response body.
-  "Received #{request.method} from #{request.url}!\n"
+  "Received #{request.request_method} from #{request.url}!\n"
 end
 ```
 
@@ -68,7 +68,7 @@ require "functions_framework"
 
 FunctionsFramework.http "logging_example" do |request|
   # Log some request info.
-  request.logger.info "I received #{request.method} from #{request.url}!"
+  request.logger.info "I received #{request.request_method} from #{request.url}!"
   # A simple response body.
   "ok"
 end
@@ -111,7 +111,7 @@ dependency on Sinatra in your `Gemfile`:
 
 ```ruby
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.9"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -197,6 +197,240 @@ FunctionsFramework.http "error_reporter" do |request|
 end
 ```
 
+## The runtime environment
+
+A serverless environment may be somewhat different from server-based runtime
+environments you might be used to. Serverless runtimes often provide a simpler
+programming model, transparent scaling, and cost savings, but they do so by
+controlling how your code is managed and executed. The Functions Framework is
+designed around a "functions-as-a-service" (FaaS) paradigm, which runs
+self-contained stateless functions that have an input and a return value. It's
+important to understand what that means for your Ruby code in order to get the
+most out of a cloud serverless product.
+
+For example, multithreading is a core element of the Functions Framework. When
+you write functions, you should assume that multiple executions may be taking
+place concurrently in different threads, and thus you should avoid operations
+that can cause concurrency issues or race conditions. The easiest way to do
+this is to make your functions self-contained and stateless. Avoid global
+variables and don't share mutable data between different function executions.
+
+Additionally, a serverless runtime may throttle the CPU whenever no actual
+function executions are taking place. This lets it reduce the CPU resources
+used (and therefore the cost to you), while keeping your application warmed up
+and ready to respond to new requests quickly. An important implication, though,
+is that you should avoid starting up background threads or processes. They may
+not get any CPU time during periods when your Ruby application is not actually
+executing a function.
+
+In the sections below, we'll discuss a few techniques and features of the
+Functions Framework to help you write Ruby code that fits well into a
+serverless paradigm.
+
+### Startup tasks
+
+It is sometimes useful to perform one-time initialization that applies to many
+function executions, for example to warm up caches, perform precomputation, or
+establish shared remote connections. To run code during initialization, use
+{FunctionsFramework.on_startup} to define a _startup task_.
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.on_startup do |function|
+  # Perform initialization here.
+  require "my_cache"
+  MyCache.warmup
+end
+
+FunctionsFramework.http "hello" do |request|
+  # Initialization will be done by the time a normal function is called.
+end
+```
+
+Startup tasks are run once per Ruby instance during cold start -- that is,
+after the Ruby VM boots up but before the framework starts receiving requests
+and executing functions. You can define multiple startup tasks, and they will
+run in order, and are guaranteed to complete before any function is executed.
+
+The block is optionally passed the {FunctionsFramework::Function} representing
+the function that will be run. You code can, for example, perform different
+initialization depending on the {FunctionsFramework::Function#name} or
+{FunctionsFramework::Function#type}.
+
+**In most cases, initialization code should live in an `on_startup` block
+instead of at the "top level" of your Ruby file.** This is because some
+serverless runtimes may load your Ruby code at build or deployment time (for
+example, to verify that it properly defines the requested function), and this
+will execute any code present at the top level of the Ruby file. If top-level
+code is long-running or depends on runtime resources or environment variables,
+this could cause the deployment to fail. By performing initialization in an
+`on_startup` block instead, you ensure it will run only when an actual runtime
+server is starting up, not at build/deployment time.
+
+```ruby
+require "functions_framework"
+
+# DO NOT perform initialization here because this could get run at build time.
+#   require "my_cache"
+#   MyCache.warmup
+
+# Instead initialize in an on_startup block, which is executed only when a
+# runtime server is starting up.
+FunctionsFramework.on_startup do
+  # Perform initialization here.
+  require "my_cache"
+  MyCache.warmup
+end
+
+# ...
+```
+
+Because startup tasks run during cold start, they could have an impact on your
+function's startup latency. To mitigate this issue, it is possible to run parts
+of your initialization lazily, as described below in the section below on
+[lazy initialization](#Lazy_initialization).
+
+### The execution context and global data
+
+When your function block executes, the _object context_ (i.e. `self`) is set to
+an instance of {FunctionsFramework::Function::Callable}. Each function
+invocation (including functions that might be running concurrently in separate
+threads) runs within a different instance, to help you avoid having functions
+interfere with each other.
+
+The object context also defines a few methods that may be useful when writing
+your function.
+
+First, you can obtain the logger by calling the
+{FunctionsFramework::Function::Callable#logger} convenience method. This is
+the same logger that is provided by the HTTP request object or by the
+{FunctionsFramework.logger} global method.
+
+Second, you can access global shared data by passing a key to
+{FunctionsFramework::Function::Callable#global}. _Global shared data_ is a set
+of key-value pairs that are available to every function invocation. By default,
+two keys are available to all functions:
+
+ *  `:function_name` whose String value is the name of the running function.
+ *  `:function_type` whose value is either `:http` or `:cloud_event` depending
+    on the type of the running function.
+
+Following is a simple example using the `logger` and `global` methods of the
+context object:
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.cloud_event "hello" do |event|
+  logger.info "Now running the function called #{global(:function_name)}"
+end
+```
+
+To avoid concurrency issues, global shared data is immutable when executing a
+function. You cannot add or delete keys or change the value of existing keys.
+However, the global data is settable during startup tasks, because startup
+tasks never run concurrently. You can use this feature to initialize shared
+resources, as described below.
+
+Using the global data mechanism is generally preferred over actual Ruby global
+variables, because the Functions Framework can help you avoid concurrent edits.
+Additionally, the framework will isolate the sets of global data associated
+with different sets of functions, which lets you run functions in isolation
+during unit tests. If you are testing multiple functions, they will not
+interfere with each other as they might if they used global variables.
+
+### Sharing resources
+
+Although functions should generally be self-contained and stateless, it is
+sometimes useful to share certain kinds of resources 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.
+
+The best practice for sharing a resource across function invocations is to
+initialize it in a {FunctionsFramework.on_startup} block, and reference it from
+global shared data. (As discussed above, the best practice is to initialize
+shared resources in a startup task rather than at the top level of a Ruby file,
+and to use the Functions Framework's global data mechanism rather than Ruby's
+global variables.)
+
+Here is a simple example:
+
+```ruby
+require "functions_framework"
+
+# Use an on_startup block to initialize a shared client and store it in
+# the global shared data.
+FunctionsFramework.on_startup do
+  require "google/cloud/storage"
+  set_global :storage_client, Google::Cloud::Storage.new
+end
+
+# The shared storage_client can be accessed by all function invocations
+# via the global shared data.
+FunctionsFramework.http "storage_example" do |request|
+  bucket = global(:storage_client).bucket "my-bucket"
+  file = bucket.file "path/to/my-file.txt"
+  file.download.to_s
+end
+```
+
+Importantly, if you do share a resource across function invocations, make sure
+the resource is thread-safe, so that separate functions running concurrently in
+different threads can access them safely. The API clients provided by Google,
+for example, are thread-safe and can be used concurrently.
+
+Also of note: There is no guaranteed cleanup hook. The Functions Framework does
+not provide a way to register a cleanup task, and we recommend against using
+resources that require explicit "cleanup". This is because serverless runtimes
+may perform CPU throttling, and therefore there may not be an opportunity for
+cleanup tasks to run. (For example, you could register a `Kernel.at_exit` task,
+but the Ruby VM may still terminate without calling it.)
+
+### Lazy initialization
+
+Because startup tasks run during cold start, they could have an impact on your
+function's startup latency. You can mitigate this by initializing some globals
+_lazily_. When setting a global, instead of computing and setting the value
+directly (e.g. constructing a shared API client object directly), you can
+provide a block that describes how to construct it on demand.
+
+Here is an example using the storage client we saw above.
+
+```ruby
+require "functions_framework"
+
+# This startup block describes _how_ to initialize a shared client, but
+# does not construct it immediately.
+FunctionsFramework.on_startup do
+  require "google/cloud/storage"
+  set_global :storage_client do
+    Google::Cloud::Storage.new
+  end
+end
+
+# The first time this function is invoked, it will call the above block
+# to construct the storage client. Subsequent invocations will not need
+# to construct it again, but will reuse the same shared object.
+FunctionsFramework.http "storage_example" do |request|
+  bucket = global(:storage_client).bucket "my-bucket"
+  file = bucket.file "path/to/my-file.txt"
+  file.download.to_s
+end
+```
+
+The block will not be called until a function actually attempts to access the
+global. From that point, subsequent accesses of the global will return that
+same shared value; the block will be called at most once. This is true even if
+multiple functions are run concurrently in different threads.
+
+Lazy initialization is particularly useful if you define several different
+functions that may use different sets of shared resources. Instead of
+initializing all resources eagerly up front, you could initialize them lazily
+and run only the code needed by the function that is actually invoked.
+
 ## Structuring a project
 
 A Functions Framework based "project" or "application" is a typical Ruby
@@ -209,12 +443,14 @@ and methods that assist in the function implementation.
 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
+to specify an arbitrary source, but some hosting environments (such as Google
 Cloud Functions) require it to be `./app.rb`.
 
 A source file can define any number of functions (with distinct names). Each of
 the names is known as a **function target**.
 
+Following is a typical layout for a Functions Framework based project.
+
 ```
 (project directory)
 |
@@ -234,13 +470,16 @@ the names is known as a **function target**.
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.9"
 ```
 
 ```ruby
 # app.rb
 require "functions_framework"
-require_relative "lib/hello"
+
+FunctionsFramework.on_startup do
+  require_relative "lib/hello"
+end
 
 FunctionsFramework.http "hello" do |request|
   Hello.new(request).build_response
@@ -255,7 +494,7 @@ class Hello
   end
 
   def build_response
-    "Received request: #{request.method} #{request.url}\n"
+    "Received request: #{@request.request_method} #{@request.url}\n"
   end
 end
 ```