functions_framework 0.1.1 → 0.4.0

data/docs/overview.md

@@ -0,0 +1,142 @@
+<!--
+# @title Functions Framework Overview
+-->
+
+# Functions Framework for Ruby
+
+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)
+ *  Any other [Knative](https://github.com/knative)-based environment
+ *  Your local development machine
+
+The framework allows you to go from:
+
+```ruby
+FunctionsFramework.http("hello") do |request|
+  "Hello, world!\n"
+end
+```
+
+To:
+
+```sh
+curl http://my-url
+# Output: Hello, world!
+```
+
+Running on a fully-managed or self-managed serverless environment, without
+requiring an HTTP server or complicated request handling logic.
+
+## Features
+
+ *  Define named functions using normal Ruby constructs.
+ *  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.
+
+## Supported Ruby versions
+
+This library is supported on Ruby 2.4+.
+
+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
+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.
+
+## Quickstart
+
+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.4"
+```
+
+Create a file called `app.rb` and include the following code. This defines a
+simple function called "hello".
+
+```ruby
+# app.rb
+require "functions_framework"
+
+FunctionsFramework.http("hello") do |request|
+  "Hello, world!\n"
+end
+```
+
+Install the bundle, and start the framework. This spins up a local web server
+running your "hello" function:
+
+```sh
+bundle install
+# ...installs the functions_framework gem and other dependencies
+bundle exec functions-framework-ruby --target hello
+# ...starts the functions server in the foreground
+```
+
+In a separate shell, you can send requests to this function using curl:
+
+```sh
+curl http://localhost:8080
+# Output: Hello, world!
+```
+
+Stop the server with `CTRL+C`.
+
+## Documentation
+
+These guides provide additional getting-started information.
+
+ *  **{file:docs/writing-functions.md Writing Functions}** :
+    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).
+ *  **{file:docs/testing-functions.md Testing Functions}** :
+    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/).
+ *  **{file:docs/running-a-functions-server.md Running a Functions Server}** :
+    How to use the `functions-framework-ruby` executable to run a local
+    functions server.
+ *  **{file:docs/deploying-functions.md Deploying Functions}** :
+    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 GitHub repository:
+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/docs/running-a-functions-server.md

@@ -0,0 +1,122 @@
+<!--
+# @title Running a Functions Server
+-->
+
+# Running a Functions Server
+
+This guide covers how to use the `functions-framework-ruby` executable to launch
+a functions server hosting Ruby functions written for the Functions Framework.
+For more information about the Framework as a whole, see the
+{file:docs/overview.md Overview Guide}.
+
+## Running functions locally
+
+The `functions-framework-ruby` command-line executable is used to run a
+functions server. This executable is installed with the `functions_framework`
+gem, and can be run with `bundle exec`. It wraps your function in a web server
+request handler, and runs it in the [Puma](https://puma.io/) web server.
+
+Pass the name of the function to run in the `--target` option. By default,
+`functions-framework-ruby` will load functions from the file `app.rb` in the
+current directory. If you want to load functions from a different file, use the
+`--source` option.
+
+```sh
+bundle install
+bundle exec functions-framework-ruby --source=foo.rb --target=hello
+```
+
+You can now send requests to your function. e.g.
+
+```sh
+curl http://localhost:8080/
+```
+
+The executable will write logs to the standard error stream while it is running.
+To stop the server, hit `CTRL+C` or otherwise send it an appropriate signal.
+The executable has no "background" or "daemon" mode. To run it in the background
+from a shell, use the shell's background syntax (such as appending `&` to the
+command).
+
+By default, the executable will listen on the port specified by the `$PORT`
+environment variable, or port 8080 if the variable is not set. You can also
+override this by passing the `--port` option. A number of other options are
+also available. See the section below on configuring the server, or pass
+`--help` to the executable to display online help.
+
+## Running functions in Docker
+
+The `functions-framework-ruby` executable is designed to be run in a Docker
+container. This is how it is run in some container-based hosting services such
+as Google Cloud Run, but you can also run it in Docker locally.
+
+First, write a Dockerfile for your project. Following is a simple 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
+ENV PORT=8080
+ENTRYPOINT ["bundle", "exec", "functions-framework-ruby"]
+```
+
+Build an image for your project using the Dockerfile.
+
+```sh
+docker build --tag my-image .
+```
+
+Then, you can run the Docker container locally as follows:
+
+```sh
+docker run --rm -it -p 8080:8080 my-image --source=foo.rb --target=hello
+```
+
+The arguments after the image name (e.g. `--source` and `--target` in the above
+example) are passed to the `functions-framework-ruby` executable.
+
+Because the docker container above maps port 8080 internally to port 8080
+externally, you can use that port to send requests to your function. e.g.
+
+```sh
+curl http://localhost:8080/
+```
+
+You can stop the running Docker container with `CTRL+C` or by sending an
+appropriate signal.
+
+## Configuring the server
+
+The Ruby Functions Framework recognizes the following command line arguments to
+the `functions-framework-ruby` executable. Each argument also corresponds to an
+environment variable. If you specify both, the flag takes precedence.
+
+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).
+`--signature-type`  | `FUNCTION_SIGNATURE_TYPE`  | Verifies that the function has the expected signature. Allowed values: `http`, `event`, or `cloudevent`.
+`--environment`     | `RACK_ENV`                 | Sets the Rack environment.
+`--bind`            | `FUNCTION_BIND_ADDR`       | Binds to the given address. Default: `0.0.0.0`.
+`--min-threads`     | `FUNCTION_MIN_THREADS`     | Sets the minimum thread pool size, overriding Puma's default.
+`--max-threads`     | `FUNCTION_MAX_THREADS`     | Sets the maximum thread pool size, overriding Puma's default.
+`--detailed-errors` | `FUNCTION_DETAILED_ERRORS` | No value. If present, shows exception details in exception responses. Defaults to false.
+`--verbose`         | `FUNCTION_LOGGING_LEVEL`   | No value. Increases log verbosity (e.g. from INFO to DEBUG). Can be given more than once.
+`--quiet`           | `FUNCTION_LOGGING_LEVEL`   | No value. Decreases log verbosity (e.g. from INFO to WARN). Can be given more than once.
+
+Detailed errors are enabled by default if the `FUNCTION_DETAILED_ERRORS`
+environment variable is set to a _non-empty_ string. The exact value does not
+matter. Detailed errors are disabled if the variable is unset or empty.
+
+The logging level defaults to the value of the `FUNCTION_LOGGING_LEVEL`
+environment variable, which can be one of the following values: `DEBUG`, `INFO`,
+`WARN`, `ERROR`, `FATAL`, or `UNKNOWN`, corresponding to Ruby's
+[Logger::Severity](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger/Severity.html)
+constants. If `FUNCTION_LOGGING_LEVEL` is not set to one of those values, it
+defaults to `INFO`.

data/docs/testing-functions.md

@@ -0,0 +1,169 @@
+<!--
+# @title Testing Functions
+-->
+
+# Testing Functions
+
+This guide covers writing unit tests for functions using the Functions Framework
+for Ruby. For more information about the Framework, see the
+{file:docs/overview.md Overview Guide}.
+
+## Overview of function testing
+
+One of the benefits of the functions-as-a-service paradigm is that functions are
+easy to test. In many cases, you can simply call a function with input, and test
+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.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+  # define tests...
+end
+```
+
+```ruby
+require "rspec"
+require "functions_framework/testing"
+
+describe "My functions" do
+  include FunctionsFramework::Testing
+  # define examples...
+end
+```
+
+## Loading functions for testing
+
+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.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+
+  def test_a_function
+    load_temporary "foo.rb" do
+      # Test a function defined in foo.rb
+    end
+  end
+
+  def test_another_function
+    load_temporary "bar.rb" do
+      # Test a function defined in bar.rb
+    end
+  end
+end
+```
+
+When running a test suite, you'll typically need to load all the Ruby files
+that define your functions. While `load_temporary` can ensure that the function
+definitions do not conflict, it cannot do the same for classes, methods, and
+other Ruby constructs. So, for testability, it is generally good practice to
+include only functions in one of these files. If you need to write supporting
+helper methods, classes, constants, or other code, include them in separate
+ruby files that you `require`.
+
+## Testing HTTP functions
+
+Testing an HTTP function is generally as simple as generating a request, calling
+the function, and asserting against the response.
+
+The input to an HTTP function is a
+[Rack::Request](https://rubydoc.info/gems/rack/Rack/Request) object. It is
+usually not hard to construct one of these objects, but the `Testing` module
+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
+[Rack::Response](https://rubydoc.info/gems/rack/Rack/Response) that you can
+assert against.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+
+  def test_http_function
+    load_temporary "app.rb" do
+      request = make_post_request "https://example.com/foo", "{\"name\":\"Ruby\"}",
+                                  ["Content-Type: application/json"]
+      response = call_http "my_function", request
+      assert_equal 200, response.status
+      assert_equal "Hello, Ruby!", response.body.join
+    end
+  end
+end
+```
+
+If the function raises an exception, the exception will be converted to a 500
+response object. So if you are testing an error case, you should still check the
+response object rather than looking for a raised exception.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+
+  def test_erroring_http_function
+    load_temporary "app.rb" do
+      request = make_post_request "https://example.com/foo", "{\"name\":\"Ruby\"}",
+                                  ["Content-Type: application/json"]
+      response = call_http "error_function", request
+      assert_equal 500, response.status
+      assert_match(/ArgumentError/, response.body.join)
+    end
+  end
+end
+```
+
+## Testing CloudEvent functions
+
+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).
+
+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
+the standard error output.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+
+  def test_event_function
+    load_temporary "app.rb" do
+      event = make_cloud_event "Hello, world!", type: "my-type"
+      _out, err = capture_subprocess_io do
+        call_event "my_function", event
+      end
+      assert_match(/Received: "Hello, world!"/, err)
+    end
+  end
+end
+```

data/docs/writing-functions.md

@@ -0,0 +1,275 @@
+<!--
+# @title Writing Functions
+-->
+
+# Writing Functions
+
+This guide covers writing functions using the Functions Framework for Ruby. For
+more information about the Framework, see the
+{file:docs/overview.md Overview Guide}.
+
+## About functions
+
+Functions are Ruby blocks that are run when an input is received. Those inputs
+can be HTTP requests or events in a recognized format. Functions that receive
+HTTP requests return an HTTP response, but event functions have no return value.
+
+When you define a function, you must provide an identifying name. The Functions
+Framework allows you to use any string as a function name; however, many
+deployment environments restrict the characters that can be used in a name. For
+maximum portability, it is recommended that you use names that are allowed for
+Ruby methods, i.e. beginning with a letter, and containing only letters,
+numbers, and underscores.
+
+## Defining an HTTP function
+
+An HTTP function is a simple web service that takes an HTTP request and returns
+an HTTP response. The following example defines an HTTP function named "hello"
+that returns a simple message in the HTTP response body:
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.http "hello" do |request|
+  # Return the response body.
+  "Hello, world!\n"
+end
+```
+
+HTTP functions take a Rack Request object and return an HTTP response. We'll
+now cover these in a bit more detail.
+
+### Using the Request object
+
+An HTTP function is passed a request, which is an object of type
+[Rack::Request](https://rubydoc.info/gems/rack/Rack/Request). This object
+provides methods for obtaining request information such as the method,
+path, query parameters, body content, and headers. You can also obtain the raw
+Rack environment using the `env` method. The following example includes some
+request information in the response:
+
+```ruby
+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"
+end
+```
+
+The Functions Framework sets up a logger in the Rack environment, so you can
+use the `logger` method on the request object if you want to emit logs. These
+logs will be written to the standard error stream, and will appear in the
+Google Cloud Logs if your function is running on a Google Cloud serverless
+hosting environment.
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.http "logging_example" do |request|
+  # Log some request info.
+  request.logger.info "I received #{request.method} from #{request.url}!"
+  # A simple response body.
+  "ok"
+end
+```
+
+### Response types
+
+The above examples return simple strings as the response body. Often, however,
+you will need to return more complex responses such as JSON, binary data, or
+even rendered HTML. The Functions Framework recognizes a variety of return
+types from an HTTP function:
+
+ *  **String** : If you return a string, the framework will use it as the
+    response body in with a 200 (success) HTTP status code. It will set the
+    `Content-Type` header to `text/plain`.
+ *  **Array** : If you return an array, the framework will assume it is a
+    standard three-element Rack response array, as defined in the
+    [Rack spec](https://github.com/rack/rack/blob/master/SPEC.rdoc).
+ *  **Rack::Response** : You can return a
+    [Rack::Response](https://rubydoc.info/gems/rack/Rack/Response) object. The
+    Framework will call `#finish` on this object and retrieve the contents.
+ *  **Hash** : If you return a Hash, the Framework will attempt to encode it as
+    JSON, and return it in the response body with a 200 (success) HTTP status
+    code. The `Content-Type` will be set to `application/json`.
+ *  **StandardError** : If you return an exception object, the Framework will
+    return a 500 (server error) response. See the section below on
+    Error Handling.
+
+### Using Sinatra
+
+The Functions Framework, and the functions-as-a-service (FaaS) solutions it
+targets, are optimized for relatively simple HTTP requests such as webhooks and
+simple APIs. If you want to deploy a large application or use a monolithic
+framework such as Ruby on Rails, you may want to consider a solution such as
+Google Cloud Run that is tailored to larger applications. However, a lightweight
+framework such as Sinatra is sometimes useful when writing HTTP functions.
+
+It is easy to connect an HTTP function to a Sinatra app. First, declare the
+dependency on Sinatra in your `Gemfile`:
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "functions_framework", "~> 0.4"
+gem "sinatra", "~> 2.0"
+```
+
+Write the Sinatra app using the "modular" Sinatra interface (i.e. subclass
+`Sinatra::Base`), and then run the Sinatra app directly as a Rack handler from
+the function. Here is a basic example:
+
+```ruby
+require "functions_framework"
+require "sinatra/base"
+
+class App < Sinatra::Base
+  get "/hello/:name" do
+    "Hello, #{params[:name]}!"
+  end
+end
+
+FunctionsFramework.http "sinatra_example" do |request|
+  App.call request.env
+end
+```
+
+This technique gives you access to pretty much any feature of the Sinatra web
+framework, including routes, templates, and even custom middleware.
+
+## Defining an Event function
+
+An event function is a handler for a standard cloud event. It can receive
+industry-standard [CloudEvents](https://cloudevents.io), as well as events sent
+by Google Cloud services such as [Pub/Sub](https://cloud.google.com/pubsub) and
+[Storage](https://cloud.google.com/storage). Event functions do not have a
+return value.
+
+The following is a simple event handler that receives an event and logs some
+information about it:
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.cloud_event "hello" do |event|
+  FunctionsFramework.logger.info "I received an event of type #{event.type}!"
+end
+```
+
+The event parameter will be either a
+[CloudEvents V0.3 Event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V0)
+object ([see spec](https://github.com/cloudevents/spec/blob/v0.3/spec.md)) or a
+[CloudEvents V1.0 Event](https://rubydoc.info/gems/functions_framework/FunctionsFramework/CloudEvents/Event/V1)
+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
+prior to CloudEvents. The Functions Framework will convert these legacy events
+to an equivalent CloudEvents V1 type, so your function will always receive a
+CloudEvent object when it is sent an event from Google Cloud. The precise
+mapping between legacy events and CloudEvents is not specified in detail here,
+but in general, the _data_ from the legacy event will be mapped to the `data`
+field in the CloudEvent, and the _context_ from the legacy event will be mapped
+to equivalent CloudEvent attributes.
+
+## Error handling
+
+If your function encounters an error, it can raise an exception. The Functions
+Framework will catch `StandardError` exceptions and handle them appropriately.
+
+If you raise an exception in an HTTP function, the Functions Framework will
+return a 500 (server error) response. You can control whether the exception
+details (e.g. exception type, message, and backtrace) are sent with the
+response by setting the detailed-errors configuration in the server. The
+Framework will also log the error for you.
+
+If you need more control over the error response, you can also construct the
+HTTP response yourself. For example:
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.http "error_reporter" do |request|
+  begin
+    raise "whoops!"
+  rescue RuntimeError => e
+    [500, {}, ["Uh, oh, got an error message: #{e.message}."]]
+  end
+end
+```
+
+## Structuring a project
+
+A Functions Framework based "project" or "application" is a typical Ruby
+application. It should include a `Gemfile` that specifies the gem dependencies
+(including the `functions_framework` gem itself), and any other dependencies
+needed by the function. It must include at least one Ruby source file that
+defines functions, and can also include additional Ruby files defining classes
+and methods that assist in the function implementation.
+
+The "entrypoint" to the project, also called the "source", is a Ruby file. It
+can define any number of functions (with distinct names), although it is often
+good practice to create a separate Ruby file per function.
+
+By convention, the source file is often called `app.rb`, but you can give it
+any name. Projects can also have multiple source files that apply to different
+cases.
+
+A simple project might look like this:
+
+```
+(project directory)
+|
++- Gemfile
+|
++- app.rb
+|
++- lib/
+|  |
+|  +- hello.rb
+|
++- test/
+   |
+   ...
+```
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "functions_framework", "~> 0.4"
+```
+
+```ruby
+# app.rb
+require "functions_framework"
+require_relative "lib/hello"
+
+FunctionsFramework.http "hello" do |request|
+  Hello.new(request).build_response
+end
+```
+
+```ruby
+# lib/hello.rb
+class Hello
+  def initialize request
+    @request = request
+  end
+
+  def build_response
+    "Received request: #{request.method} #{request.url}\n"
+  end
+end
+```
+
+## Next steps
+
+To learn about writing unit tests for functions, see
+{file:docs/testing-functions.md Testing Functions}.
+
+To learn how to run your functions in a server, see
+{file:docs/running-a-functions-server.md Running a Functions Server}.
+
+To learn how to deploy your functions to Google Cloud Functions or Google Cloud
+Run, see
+{file:docs/deploying-functions.md Deploying Functions}.