module FunctionsFramework

The Functions Framework for Ruby.

Functions Framework is an open source framework for writing lightweight, portable Ruby functions that run in a serverless environment. For general information about the Functions Framework, see github.com/GoogleCloudPlatform/functions-framework. To get started with the functions framework for Ruby, see github.com/GoogleCloudPlatform/functions-framework-ruby for basic examples.

## Inside the FunctionsFramework module

The FunctionsFramework module includes the main entry points for the functions framework. Use the {FunctionsFramework.http}, {FunctionsFramework.event}, or {FunctionsFramework.cloud_event} methods to define functions. To serve functions via a web service, invoke the `functions-framework-ruby` executable, or use the {FunctionsFramework.start} or {FunctionsFramework.run} methods.

## Internal modules

Here is a roadmap to the internal modules in the Ruby functions framework.

*  {FunctionsFramework::CLI} is the implementation of the
   `functions-framework-ruby` executable. Most apps will not need to interact
   with this class directly.
*  {FunctionsFramework::Function} is the internal representation of a
   function, indicating the type of function (http or cloud event), the
   name of the function, and the block of code implementing it. Most apps
   do not need to interact with this class directly.
*  {FunctionsFramework::Registry} looks up functions by name. When you
   define a set of named functions, they are added to a registry, and when
   you start a server and specify the target function by name, it is looked
   up from the registry. Most apps do not need to interact with this class
   directly.
*  {FunctionsFramework::Server} is a web server that makes a function
   available via HTTP. It wraps the Puma web server and runs a specific
   {FunctionsFramework::Function}. Many apps can simply run the
   `functions-framework-ruby` executable to spin up a server. However, if you
   need closer control over your execution environment, you can use the
   {FunctionsFramework::Server} class to run a server. Note that, in most
   cases, it is easier to use the {FunctionsFramework.start} or
   {FunctionsFramework.run} wrapper methods rather than instantiate a
   {FunctionsFramework::Server} class directly.
*  {FunctionsFramework::Testing} provides helpers that are useful when
   writing unit tests for functions.

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.

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

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

Constants

CloudEvents

The CloudEvents implementation was extracted to become the official CloudEvents SDK. This alias is left here for backward compatibility.

DEFAULT_SOURCE

The default source file path. The CLI loads functions from this file if no source file is given explicitly.

@return [String]

DEFAULT_TARGET

The default target function name. If you define a function without specifying a name, or run the framework without giving a target, this name is used.

@return [String]

VERSION

Version of the Ruby Functions Framework @return [String]

Attributes

global_registry[RW]

The “global” registry that holds events defined by the {FunctionsFramework} class methods.

@return [FunctionsFramework::Registry]

logger[RW]

A “global” logger that is used by the framework's web server, and can also be used by functions.

@return [Logger]

Public Class Methods

cloud_event(name = DEFAULT_TARGET, &block) click to toggle source

Define a function that responds to CloudEvents.

You must provide a name for the function, and a block that implemets the function. The block should take one argument: the event object of type [`CloudEvents::Event`](cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event). Any return value is ignored.

## Example

FunctionsFramework.cloud_event "my-function" do |event|
  FunctionsFramework.logger.info "Event data: #{event.data.inspect}"
end

@param name [String] The function name. Defaults to {DEFAULT_TARGET}. @param block [Proc] The function code as a proc. @return [self]

# File lib/functions_framework.rb, line 163
def cloud_event name = DEFAULT_TARGET, &block
  global_registry.add_cloud_event name, &block
  self
end

http(name = DEFAULT_TARGET, &block) click to toggle source

Define a function that response to HTTP requests.

You must provide a name for the function, and a block that implemets the function. The block should take a single `Rack::Request` argument. It should return one of the following:

*  A standard 3-element Rack response array. See
   https://github.com/rack/rack/blob/master/SPEC
*  A `Rack::Response` object.
*  A simple String that will be sent as the response body.
*  A Hash object that will be encoded as JSON and sent as the response
   body.

## Example

FunctionsFramework.http "my-function" do |request|
  "I received a request for #{request.url}"
end

@param name [String] The function name. Defaults to {DEFAULT_TARGET}. @param block [Proc] The function code as a proc. @return [self]

# File lib/functions_framework.rb, line 140
def http name = DEFAULT_TARGET, &block
  global_registry.add_http name, &block
  self
end

on_startup(&block) click to toggle source

Define a server startup task. This is useful for initializing shared resources that should be accessible across all function invocations in this Ruby VM.

Startup tasks are run just before a server starts. All startup tasks are guaranteed to complete before any function executes. However, they are run only when preparing to run functions. They are not run, for example, if an app is loaded to verify its integrity during deployment.

Startup tasks are passed the {FunctionsFramework::Function} identifying the function to execute, and have no return value.

@param block [Proc] The startup task @return [self]

# File lib/functions_framework.rb, line 184
def on_startup &block
  global_registry.add_startup_task(&block)
  self
end

run(target, &block) click to toggle source

Run the functions framework server and block until it stops. The server will look up the given target function name in the global registry.

@param target [FunctionsFramework::Function,String] The function to run,

or the name of the function to look up in the global registry.

@yield [FunctionsFramework::Server::Config] A config object that can be

manipulated to configure the server.

@return [self]

# File lib/functions_framework.rb, line 228
def run target, &block
  server = start target, &block
  server.wait_until_stopped
  self
end

start(target, &block) click to toggle source

Run startup tasks, then start the functions framework server in the background. The startup tasks and target function will be looked up in the global registry.

@param target [FunctionsFramework::Function,String] The function to run,

or the name of the function to look up in the global registry.

@yield [FunctionsFramework::Server::Config] A config object that can be

manipulated to configure the server.

@return [FunctionsFramework::Server]

# File lib/functions_framework.rb, line 200
def start target, &block
  require "functions_framework/server"
  if target.is_a? ::FunctionsFramework::Function
    function = target
  else
    function = global_registry[target]
    raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
  end
  globals = function.populate_globals
  server = Server.new function, globals, &block
  global_registry.startup_tasks.each do |task|
    task.call function, globals: globals, logger: server.config.logger
  end
  globals.freeze
  server.respond_to_signals
  server.start
end