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.4.2".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 implements 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) 


193
194
195
196
 
# File 'lib/functions_framework.rb', line 193

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 responds to HTTP requests.

You must provide a name for the function, and a block that implements 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/main/SPEC.rdoc
  • 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) 


214
215
216
217
 
# File 'lib/functions_framework.rb', line 214

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) 


258
259
260
261
262
 
# File 'lib/functions_framework.rb', line 258

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:



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/functions_framework.rb', line 230

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

.typed(name = DEFAULT_TARGET, request_class: nil, &block) ⇒ self

Define a Typed function that responds to HTTP requests.

You must provide a name for the function, and a block that implements the function. The block should take a single argument representing the request payload. If a request_type is provided, the argument object will be of the given decoded type; otherwise, it will be a JSON hash. The block should return a JSON hash or an object that implements #to_json.

Example

FunctionsFramework.typed "my-sum-function" do |add_request|
  {sum: add_request["num1"] + add_response["num2"]}
end

Example with Type

FunctionsFramework.typed "identity",
                        request_class: MyCustomType do |custom_type|
  custom_type
end

Parameters:

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

    The function name. Defaults to DEFAULT_TARGET

  • request_class (#decode_json) (defaults to: nil) —

    An optional class which will be used to decode the request if it implements a decode_json static method.

  • block (Proc) —

    The function code as a proc @return [self]

Returns:

  • (self) 


170
171
172
173
 
# File 'lib/functions_framework.rb', line 170

def typed name = DEFAULT_TARGET, request_class: nil, &block
  global_registry.add_typed name, request_class: request_class, &block
  self
end