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 (coming soon)
• Cloud Run or Cloud Run for Anthos
• Any other Knative-based environment
• Your local development machine

The framework allows you to go from:

FunctionsFramework.http do |request|
  "Hello, world!\n"
end

To:

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

• Define named functions using normal Ruby constructs.
• Invoke functions in response to requests.
• Automatically unmarshal events conforming to the CloudEvents spec.
• Spin up a local development server for quick testing.
• Integrate with standard Ruby libraries such as Rack and Minitest.
• Portable between serverless platforms.

Install the Functions Framework via Rubygems:

gem install functions_framework

Or add it to your Gemfile for installation using Bundler:

# Gemfile
gem "functions_framework", "~> 0.1"

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.

Create a Gemfile listing the Functions Framework as a dependency:

# Gemfile
source "https://rubygems.org"
gem "functions_framework", "~> 0.1"

Create a file called app.rb and include the following code. This defines a simple function called "hello".

# 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:

bundle install
# ...installs the functions_framework gem and other dependencies
bundle exec functions-framework --target hello
# ...starts the web server in the foreground

In a separate shell, you can send requests to this function using curl:

curl localhost:8080
# Output: Hello, world!

Stop the web server with CTRL+C.

(Google Cloud Functions does not yet support the Ruby Function Framework)

Create a Dockerfile for your function:

# 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:

gcloud builds submit --tag=gcr.io/[YOUR-PROJECT]/hello:build-1

Deploy to Cloud Run:

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.

You can also define a function that response to CloudEvents. The Functions Framework will handle unmarshalling of the event data.

Change app.rb to read:

# 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:

bundle install
bundle exec functions-framework --target my-handler

In a separate shell, you can send a CloudEvent to this function using curl:

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.

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.

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:

functions-framework --help

• See the examples directory for additional examples
• Consult https://rubydoc.info/gems/functions_framework for full reference documentation.