Module: FunctionsFramework

Defined in:
lib/functions_framework/version.rb,
lib/functions_framework/cli.rb,
lib/functions_framework/server.rb,
lib/functions_framework/testing.rb,
lib/functions_framework/function.rb,
lib/functions_framework/registry.rb,
lib/functions_framework/legacy_event_converter.rb,
lib/functions_framework.rb

Overview

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 https://github.com/GoogleCloudPlatform/functions-framework. To get started with the functions framework for Ruby, see https://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, 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.

  • CLI is the implementation of the functions-framework-ruby executable. Most apps will not need to interact with this class directly.
  • 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.
  • 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.
  • Server is a web server that makes a function available via HTTP. It wraps the Puma web server and runs a specific 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 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 Server class directly.
  • Testing provides helpers that are useful when writing unit tests for functions.

Defined Under Namespace

Modules: Testing Classes: CLI, Function, LegacyEventConverter, Registry, Server

Constant Summary collapse

VERSION =

Version of the Ruby Functions Framework

Returns:

  • (String) 
"0.5.1".freeze
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.

Returns:

  • (String) 
"function".freeze
DEFAULT_SOURCE =

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

Returns:

  • (String) 
"./app.rb".freeze
CloudEvents =

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

::CloudEvents

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.global_registry ⇒ FunctionsFramework::Registry

The "global" registry that holds events defined by the FunctionsFramework class methods.

Returns:



107
108
109
 
# File 'lib/functions_framework.rb', line 107

def global_registry
  @global_registry
end

.logger ⇒ Logger

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

Returns:

  • (Logger) 


115
116
117
 
# File 'lib/functions_framework.rb', line 115

def logger
  @logger
end

Class Method Details

.cloud_event(name = DEFAULT_TARGET, &block) ⇒ self

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. Any return value is ignored.

Example

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

Parameters:

  • name (String) (defaults to: DEFAULT_TARGET) —

    The function name. Defaults to DEFAULT_TARGET.

  • block (Proc) —

    The function code as a proc.

Returns:

  • (self) 


163
164
165
166
 
# 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) ⇒ self

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

Parameters:

  • name (String) (defaults to: DEFAULT_TARGET) —

    The function name. Defaults to DEFAULT_TARGET.

  • block (Proc) —

    The function code as a proc.

Returns:

  • (self) 


140
141
142
143
 
# File 'lib/functions_framework.rb', line 140

def http name = DEFAULT_TARGET, &block
  global_registry.add_http name, &block
  self
end

.run(target) {|FunctionsFramework::Server::Config| ... } ⇒ self

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

Parameters:

Yields:

Returns:

  • (self) 


201
202
203
204
205
 
# File 'lib/functions_framework.rb', line 201

def run target, &block
  server = start target, &block
  server.wait_until_stopped
  self
end

.start(target) {|FunctionsFramework::Server::Config| ... } ⇒ FunctionsFramework::Server

Start the functions framework server in the background. The server will look up the given target function name in the global registry.

Parameters:

Yields:

Returns:



178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/functions_framework.rb', line 178

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
  server = Server.new function, &block
  server.respond_to_signals
  server.start
end