functions_framework 0.1.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1458a2e7cef4ad3841ae328a79cd95ee8a5eea0091fb9dd6e618d443725a304a
-  data.tar.gz: 6294b3dcf3ec251ba3c026588b5eb28559353a9e09316ff9965b25a81511d725
+  metadata.gz: cdf75f322fe9e9e78b5e65bfcc9682097606deffb46137d85b6b1cfde68d3ab8
+  data.tar.gz: 54f8e668875607738141963c70b1960da6c06df69083a7ef4357f66889e1a328
 SHA512:
-  metadata.gz: ec252cf13280072a0882292326b5b9d881efef8db349268f2d380996fc94180fbb203707d47f92d3c0dee31758f8f733b26a24219191df523cd8420f3562ba3e
-  data.tar.gz: 44eb7e2c387710b77e0cf2676f00aaf259e67f84a1bad1b1b531c130b1cf37140681833bf5004d224ba82f0912f5dc6e0ebb2686e50be2cf0350c9ff7df9d821
+  metadata.gz: 3d6fd59bc3730333e91a049d03089169720390f5f9300420449480924800d97da118a87cdae33224644c3550fe78dfee4a07b18e32e534d9bb7645340fbdf4c9
+  data.tar.gz: 897cef8cc366475123250d4c9a7cea0ccd07989c9ebdc0d88d358d996c5fa727aa9bcc5eb46be286d38e72a9d2512adfbaed743975d0300502516db9e3a5fde2

data/.yardopts

@@ -2,9 +2,13 @@
 --title=Functions Framework
 --markup markdown
 --markup-provider redcarpet
---main=README.md
+--main=docs/overview.md
 ./lib/functions_framework/**/*.rb
 ./lib/functions_framework.rb
 -
-README.md
+docs/overview.md
+docs/writing-functions.md
+docs/testing-functions.md
+docs/running-a-functions-server.md
+docs/deploying-functions.md
 CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+### v0.4.0 / 2020-06-29
+
+* Dropped the legacy and largely unsupported `:event` function type. All event functions should be of type `:cloud_event`.
+* Define the object context for function execution, and include an extensible context helper.
+* Support for CloudEvents with specversion 0.3.
+* CloudEvents now correct percent-encodes/decodes binary headers.
+* CloudEvents now includes more robust RFC 2045 parsing of the Content-Type header.
+* The CloudEventsError class now properly subclasses StandardError instead of RuntimeError.
+* Removed redundant `_string` accessors from event classes since raw forms are already available via `[]`.
+* A variety of corrections to event-related class documentation.
+
+### v0.3.1 / 2020-06-27
+
+* Fixed crash when using "return" directly in a function block.
+* Added a more flexible request generation helper in the testing module.
+* Fixed several typos in the documentation.
+
+### v0.3.0 / 2020-06-26
+
+* Updated the CloudEvent data format for converted pubsub events to conform to Cloud Run's conversion.
+
+### v0.2.1 / 2020-06-25
+
+* The `--signature-type` check recognizes the legacy `event` type for `:cloud_event` functions.
+
+### v0.2.0 / 2020-06-24
+
+Significant changes:
+
+* Converts legacy GCF events and passes them to functions as CloudEvents.
+* The executable is now named `functions-framework-ruby` to avoid collisions with functions frameworks for other languages.
+* Deprecated the `event` function type. Use `cloud_event`.
+* The CloudEvents implementation is now fully-featured and can encode as well as decode events.
+* Wrote an expanded set of getting-started documentation.
+
+Minor changes:
+
+* `Testing.load_temporary` now caches loaded functions so they don't have to be reloaded for subsequent tests.
+* The executable recognizes the `--signature-type` flag, and verifies that the type is correct.
+* Error reporting is expanded and improved.
+* Fixed a crash when a batch CloudEvent was received. (These are still not supported, and now result in a 400.)
+* Renamed a few undocumented environment variables, and added support for a logging level environment variable. All CLI flags now have associated environment variables.
+* Several fixes to the example code, and added a new Sinatra example.
+
 ### v0.1.1 / 2020-02-27
 
 * Server returns 404 when receiving a /favicon.ico or /robots.txt request.

data/README.md

@@ -4,7 +4,7 @@ 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) *(coming soon)*
+ *  [Google Cloud Functions](https://cloud.google.com/functions) *(in preview)*
  *  [Cloud Run or Cloud Run for Anthos](https://cloud.google.com/run)
  *  Any other [Knative](https://github.com/knative)-based environment
  *  Your local development machine
@@ -12,7 +12,7 @@ in many different environments, including:
 The framework allows you to go from:
 
 ```ruby
-FunctionsFramework.http do |request|
+FunctionsFramework.http("hello") do |request|
   "Hello, world!\n"
 end
 ```
@@ -24,11 +24,8 @@ curl http://my-url
 # Output: Hello, world!
 ```
 
-All without needing to worry about writing an HTTP server or complicated
-request handling logic.
-
-For more information about the Functions Framework, see
-https://github.com/GoogleCloudPlatform/functions-framework
+Running on a fully-managed or self-managed serverless environment, without
+requiring an HTTP server or complicated request handling logic.
 
 ## Features
 
@@ -36,26 +33,14 @@ https://github.com/GoogleCloudPlatform/functions-framework
  *  Invoke functions in response to requests.
  *  Automatically unmarshal events conforming to the
     [CloudEvents](https://cloudevents.io) spec.
+ *  Automatically convert most legacy events from Google Cloud services such
+    as Cloud Pub/Sub and Cloud Storage, to CloudEvents.
  *  Spin up a local development server for quick testing.
  *  Integrate with standard Ruby libraries such as Rack and Minitest.
  *  Portable between serverless platforms.
+ *  Supports all non-end-of-life versions of Ruby.
 
-## Installation
-
-Install the Functions Framework via Rubygems:
-
-```sh
-gem install functions_framework
-```
-
-Or add it to your Gemfile for installation using Bundler:
-
-```ruby
-# Gemfile
-gem "functions_framework", "~> 0.1"
-```
-
-### Supported Ruby versions
+## Supported Ruby versions
 
 This library is supported on Ruby 2.4+.
 
@@ -68,14 +53,14 @@ about the Ruby support schedule.
 
 ## Quickstart
 
-### Running Hello World on your local machine
+Here is how to run a Hello World function on your local machine.
 
 Create a `Gemfile` listing the Functions Framework as a dependency:
 
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.1"
+gem "functions_framework", "~> 0.4"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a
@@ -96,123 +81,58 @@ running your "hello" function:
 ```sh
 bundle install
 # ...installs the functions_framework gem and other dependencies
-bundle exec functions-framework --target hello
+bundle exec functions-framework-ruby --target hello
 # ...starts the web server in the foreground
 ```
 
 In a separate shell, you can send requests to this function using curl:
 
 ```sh
-curl localhost:8080
+curl http://localhost:8080
 # Output: Hello, world!
 ```
 
-Stop the web server with `CTRL+C`.
-
-### Deploying a function to Google Cloud Functions
-
-(Google Cloud Functions does not yet support the Ruby Function Framework)
-
-### Deploying a function to Cloud Run
-
-Create a `Dockerfile` for your function:
-
-```dockerfile
-# Dockerfile
-FROM ruby:2.6
-
-WORKDIR /app
-COPY . .
-RUN gem install --no-document bundler \
-    && bundle config --local frozen true \
-    && bundle install
-
-ENTRYPOINT ["bundle", "exec", "functions-framework"]
-CMD ["--target", "hello"]
-```
-
-Build your function into a Docker image:
-
-```sh
-gcloud builds submit --tag=gcr.io/[YOUR-PROJECT]/hello:build-1
-```
-
-Deploy to Cloud Run:
-
-```sh
-gcloud run deploy hello --image=gcr.io/[YOUR-PROJECT]/hello:build-1 \
-  --platform=managed --allow-unauthenticated --region=us-central1
-```
-
-You can use a similar approach to deploy to any other Knative-based serverless
-environment.
-
-### Responding to CloudEvents
-
-You can also define a function that response to
-[CloudEvents](https://cloudevents.io). The Functions Framework will handle
-unmarshalling of the event data.
-
-Change `app.rb` to read:
-
-```ruby
-# app.rb
-require "functions_framework"
-
-FunctionsFramework.event("my-handler") do |data, context|
-  FunctionsFramework.logger.info "I received #{data.inspect}"
-end
-```
-
-Start up the framework with this new function:
-
-```sh
-bundle install
-bundle exec functions-framework --target my-handler
-```
-
-In a separate shell, you can send a CloudEvent to this function using curl:
-
-```sh
-curl --header "Content-Type: text/plain; charset=utf-8" \
-     --header "CE-ID: 12345" \
-     --header "CE-Source: curl" \
-     --header "CE-Type: com.example.test" \
-     --header "CE-Specversion: 1.0" \
-     --data "Hello, world!" \
-     http://localhost:8080
-```
-
-CloudEvents functions do not return meaningful results, but you will see the
-log message from the web server.
-
-### Configuring the Functions Framework
-
-The Ruby Functions Framework recognizes the standard command line arguments to
-the `functions-framework` executable. Each argument also corresponds to an
-environment variable. If you specify both, the environment variable will be
-ignored.
-
-Command-line flag | Environment variable | Description
------------------ | -------------------- | -----------
-`--port`          | `PORT`               | The port on which the Functions Framework listens for requests. Default: `8080`
-`--target`        | `FUNCTION_TARGET`    | The name of the exported function to be invoked in response to requests. Default: `function`
-`--source`        | `FUNCTION_SOURCE`    | The path to the file containing your function. Default: `app.rb` (in the current working directory)
-
-Note: the flag `--signature-type` and corresponding environment variable
-`FUNCTION_SIGNATURE_TYPE` are not used by the Ruby Function Framework, because
-you specify the signature type when defining the function in the source.
-
-The Ruby `functions-framework` executable also recognizes several additional
-flags that can be used to control logging verbosity, binding, and other
-parameters. For details, see the online help:
-
-```sh
-functions-framework --help
-```
-
-## For more information
-
- *  See the `examples` directory for additional examples
- *  Consult https://rubydoc.info/gems/functions_framework for full reference
-    documentation.
+Stop the server with `CTRL+C`.
+
+## Documentation
+
+These guides provide additional getting-started information.
+
+ *  **[Writing Functions](https://rubydoc.info/gems/functions_framework/file/docs/writing-functions.md)**
+    : 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)**
+    : 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)**
+    : 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)**
+    : 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
+
+Additional examples are available in the `examples` directory:
+https://github.com/GoogleCloudPlatform/functions-framework-ruby/blob/master/examples/
+
+## Development
+
+The source for the Ruby Functions Framework is available on GitHub at
+https://github.com/GoogleCloudPlatform/functions-framework-ruby. For more
+information on the Functions Framework contract implemented by this framework,
+as well as links to Functions Frameworks for other languages, see
+https://github.com/GoogleCloudPlatform/functions-framework.
+
+The Functions Framework is open source under the Apache 2.0 license.
+Contributions are welcome. Please see the contributing guide at
+https://github.com/GoogleCloudPlatform/functions-framework-ruby/blob/master/.github/CONTRIBUTING.md.
+
+Report issues at
+https://github.com/GoogleCloudPlatform/functions-framework-ruby/issues.

data/bin/functions-framework-ruby

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "functions_framework/cli"
+
+::FunctionsFramework::CLI.new.parse_args(::ARGV).run

data/docs/deploying-functions.md

@@ -0,0 +1,182 @@
+<!--
+# @title Deploying Functions
+-->
+
+# Deploying Functions
+
+This guide covers how to deploy your Ruby functions written with the Functions
+Framework. Functions can be deployed to
+[Google Cloud Functions](https://cloud.google.com/functions), Google's
+Functions-as-a-service (FaaS) product, to
+[Google Cloud Run](https://cloud.google.com/run). Google's container-based
+serverless environment, or to any KNative-based environment.
+For more information about the Framework as a whole, see the
+{file:docs/overview.md Overview Guide}.
+
+## Before you begin
+
+To deploy to Google Cloud, whether to Cloud Functions or Cloud Run, you'll need
+a Google Cloud project with billing enabled. Go to the
+[Google Cloud console](https://console.cloud.google.com/), create a project (or
+select an existing project), and ensure billing is enabled.
+
+Additionally, install the [Google Cloud SDK](https://cloud.google.com/sdk) if
+you haven't done so previously.
+
+## Deploying to Cloud Functions
+
+Google Cloud Functions is Google's scalable pay-as-you-go Functions-as-a-Service
+(FaaS) environment that can run your function with zero server management. The
+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.
+
+### Deploying and updating your function
+
+Before you can deploy to Cloud Functions, 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. 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".)
+
+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
+```
+
+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`.
+
+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.
+
+### Configuring Cloud Functions deployments
+
+The Functions Framework provides various configuration parameters, described in
+{file:docs/running-a-functions-server.md Running a Functions Server}.
+If you want to set any of these parameters beyond the source file and target,
+you must set environment variables. For example, to limit logging to WARN level
+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 \
+  --entry-point=$YOUR_FUNCTION_TARGET \
+  --set-env-vars=FUNCTION_LOGGING_LEVEL=WARN
+```
+
+Consult the table in
+{file:docs/running-a-functions-server.md Running a Functions Server}
+for a list of the environment variables that can be set.
+
+## Deploying to Cloud Run
+
+Google Cloud Run is Google's managed compute platform for deploying and scaling
+containerized applications quickly and securely. It can run any container-based
+workload, including a containerized function.
+
+Cloud Run has a hosted fully-managed option that runs on Google's infrastructure
+and monitors and scales your application automatically, and a self-managed or
+on-prem option called Cloud Run for Anthos that runs atop Kubernetes. Both
+flavors use the same general interface and can run functions in the same way.
+This tutorial is written for the managed option, but it should not be difficult
+to adapt it if you have an Anthos installation.
+
+### Building an image for your function
+
+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:
+
+```
+FROM ruby:2.6
+WORKDIR /app
+COPY . .
+RUN gem install --no-document bundler \
+    && bundle config --local frozen true \
+    && bundle config --local without "development test" \
+    && bundle install
+ENTRYPOINT ["bundle", "exec", "functions-framework-ruby"]
+```
+
+You can test your image locally using the steps described under
+{file:docs/running-a-functions-server.md Running a Functions Server}.
+
+When your Dockerfile is ready, you can use
+[Cloud Build](https://cloud.google.com/cloud-build) to build it and store the
+image in your project's container registry.
+
+```sh
+gcloud builds submit --tag=gcr.io/$YOUR_PROJECT_ID/$YOUR_APP_NAME:$YOUR_BUILD_ID .
+```
+
+You must use your project ID, but you can choose an app name and build ID. The
+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.
+
+### Deploying an image to Cloud Run
+
+To deploy to Cloud Run, specify the same image URL that you built above. For
+example:
+
+```sh
+gcloud run deploy $YOUR_APP_NAME --project=$YOUR_PROJECT_ID \
+  --image=gcr.io/$YOUR_PROJECT_ID/$YOUR_APP_NAME:$YOUR_BUILD_ID \
+  --platform=managed --allow-unauthenticated --region=us-central1 \
+  --set-env-vars=FUNCTION_SOURCE=$YOUR_SOURCE,FUNCTION_TARGET=$YOUR_TARGET
+```
+
+You can omit the `--project` flag if you've already set it as the default with
+`gcloud config set project`.
+
+The command may ask you for permission to enable the Cloud Run API for the
+project, if it isn't already enabled.
+
+At the end of the deployment process, the command will display the hostname for
+the Cloud Run service. You can use that hostname to send test requests to your
+deployed function.
+
+### Configuring Cloud Run deployments
+
+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
+values, you need to set the appropriate environment variables when deploying, as
+illustrated above with the `FUNCTION_SOURCE` and `FUNCTION_TARGET` variables.
+
+Source and target are not the only configuration parameters available. The
+various parameters, along with their environment variables, are described in
+{file:docs/running-a-functions-server.md Running a Functions Server}.
+Any of these can be specified in the `--set-env-vars` flag when you deploy to
+Google Cloud Run.
+
+It is also possible to "hard-code" configuration into the Dockerfile, by setting
+environment variables in the Dockerfile, or adding flags to the entrypoint.
+However, it is often better practice to keep your Dockerfile "generic", and set
+configuration environment variables during deployment, so that you do not need
+to rebuild your Docker image every time you want to change configuration.