functions_framework 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1458a2e7cef4ad3841ae328a79cd95ee8a5eea0091fb9dd6e618d443725a304a
-  data.tar.gz: 6294b3dcf3ec251ba3c026588b5eb28559353a9e09316ff9965b25a81511d725
+  metadata.gz: d3591e5ab03b6e29d0a7f9b9c16d4d470138fbf0ddebec875e80f5f1df8a9767
+  data.tar.gz: 50ed98f079c42638fcb3328bab3d1388e323613ea310842bcd3d887b1a96fdfb
 SHA512:
-  metadata.gz: ec252cf13280072a0882292326b5b9d881efef8db349268f2d380996fc94180fbb203707d47f92d3c0dee31758f8f733b26a24219191df523cd8420f3562ba3e
-  data.tar.gz: 44eb7e2c387710b77e0cf2676f00aaf259e67f84a1bad1b1b531c130b1cf37140681833bf5004d224ba82f0912f5dc6e0ebb2686e50be2cf0350c9ff7df9d821
+  metadata.gz: 87a9631c32f05b5e5831f50e9dd7235351fd6556fb22474d655a916ceacf1d57e1d25a60369c31aa3790a9667cafec02dafad2ccf9c98499a681badf2516d13e
+  data.tar.gz: 755d890b0684d2af126306c3b7f7f2e5d3b1392b0fb88e325b45eba6c85d9d6cc28e320e20a8a9d716244e52e63fee839ab02ec56014873c62dd77f3fe4ea37c

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,24 @@
 # Changelog
 
+### 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.2"
 ```
 
 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 https://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,169 @@
+<!--
+# @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.
+
+### 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.
+
+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.
+
+### 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.