functions_framework 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 370556a72cd31e4d24499b0715ca7f96a0598cb856fb28fed3d3eaabee0a80ae
-  data.tar.gz: 04a24cf1e2f205fe124eb0bda891f647177b93c43ba1c2286ed52ffbad18cb1d
+  metadata.gz: f6d562086a839aaf78661b9417d3b931df10c74c98cb07b1710d40d6294b0490
+  data.tar.gz: fd070c121ce3e0c1bab7f1a738178a37c72c5d25c7726d3f3540e687d01bbe25
 SHA512:
-  metadata.gz: 34d91fa0417632a253ddba1db7aa85f54697eb645caaaf96c9253a36fca241bca80bf17a40796dd5c8521d2c7bbe04ff23353764491d28b5e4335e0ee022f05a
-  data.tar.gz: 0d8d59ef3e45d3980136d7015e8066052bffe3942c442f715368dcf6ac5dd98b0cb282c313fa1a387ac70514747701e75c879c549faa9802444fe6b4d56115c7
+  metadata.gz: 478554bfc8b8bafb2efd5bb880b8e053e2442a878bcd1363a4c6ddeab77a811b49530b84f467009b01f2299b70105f17a8a9840d9b35ebbec94359ca14d7114c
+  data.tar.gz: 6873da52a257f542cb782fde59ba7da7f96042f4b69eaf470ea23d81cdb8479e8ff2791a6fbd0fd36ec166039f9718b7ce1b14632c690b44bea2833e280835b5

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+### 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 
+* 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.

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 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) *(in preview)*
- *  [Cloud Run or Cloud Run for Anthos](https://cloud.google.com/run)
+ *  [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.7"
 ```
 
 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,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 preview.
-> 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
 
@@ -46,30 +42,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=ruby27 \
+    --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
 
@@ -81,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
 ```
@@ -116,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 \
@@ -142,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,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) *(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.7"
 ```
 
 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
@@ -167,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
@@ -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.5"
+gem "functions_framework", "~> 0.7"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -158,9 +157,9 @@ end
 ```
 
 The event parameter will be either a
-[CloudEvents V0.3 Event](https://rubydoc.info/gems/cloud_events/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/cloud_events/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,192 @@ 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, 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
+
+# ...
+```
+
+### 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 test functions in isolation
+without the tests interfering with one another by writing to 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, prefer to initialize shared resources
+in a startup task rather than at the top level of a Ruby file, and prefer using
+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.)
+
 ## Structuring a project
 
 A Functions Framework based "project" or "application" is a typical Ruby
@@ -207,15 +392,16 @@ 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 "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 some hosting environments (such as Google
+Cloud Functions) require it to be `./app.rb`.
 
-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.
+A source file can define any number of functions (with distinct names). Each of
+the names is known as a **function target**.
 
-A simple project might look like this:
+Following is a typical layout for a Functions Framework based project.
 
 ```
 (project directory)
@@ -236,13 +422,16 @@ A simple project might look like this:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.7"
 ```
 
 ```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
@@ -257,7 +446,7 @@ class Hello
   end
 
   def build_response
-    "Received request: #{request.method} #{request.url}\n"
+    "Received request: #{@request.request_method} #{@request.url}\n"
   end
 end
 ```