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) 
"1.1.0".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

.on_startup(&block) ⇒ self

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 Function identifying the function to execute, and have no return value.

Parameters:

  • block (Proc) —

    The startup task

Returns:

  • (self) 


184
185
186
187
 
# File 'lib/functions_framework.rb', line 184

def on_startup &block
  global_registry.add_startup_task(&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) 


228
229
230
231
232
 
# File 'lib/functions_framework.rb', line 228

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

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

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.

Parameters:

Yields:

Returns:



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# 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