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/cloud_events.rb,
lib/functions_framework/cloud_events/event.rb,
lib/functions_framework/cloud_events/content_type.rb,
lib/functions_framework/cloud_events/binary_content.rb,
lib/functions_framework/cloud_events/json_structure.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, FunctionsFramework.event, or FunctionsFramework.cloud_event methods to define functions. To serve functions via a web service, invoke the functions-framework 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.

  • CloudEvents provides an implementation of the CloudEvents specification. In particular, if you define an event function, you will receive the event as a CloudEvents::Event object.
  • CLI is the implementation of the functions-framework 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 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: CloudEvents, Testing Classes: CLI, Function, Registry, Server

Constant Summary collapse

VERSION =

Version of the Ruby Functions Framework

Returns:

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

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:



103
104
105
 
# File 'lib/functions_framework.rb', line 103

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) 


111
112
113
 
# File 'lib/functions_framework.rb', line 111

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 FunctionsFramework::CloudEvents::Event. Any return value is ignored.

See also event which creates a function that takes data and context as separate arguments.

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) 


199
200
201
202
 
# File 'lib/functions_framework.rb', line 199

def cloud_event name = DEFAULT_TARGET, &block
  global_registry.add_cloud_event name, &block
  self
end

.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 two arguments: the event data and the event context. Any return value is ignored.

The event data argument will be one of the following types:

  • A String (with encoding ASCII-8BIT) if the data is in the form of binary data. You may choose to perform additional interpretation of the binary data using information in the content type provided by the context argument.
  • Any data type that can be represented in JSON (i.e. String, Integer, Array, Hash, true, false, or nil) if the event came with a JSON payload. The content type may also be set in the context if the data is a String.

The context argument will be of type FunctionsFramework::CloudEvents::Event, and will contain CloudEvents context attributes such as id and type.

See also cloud_event which defines a function that takes a single argument of type FunctionsFramework::CloudEvents::Event.

Example

FunctionsFramework.event "my-function" do |data, context|
  FunctionsFramework.logger.info "Event data: #{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) 


174
175
176
177
 
# File 'lib/functions_framework.rb', line 174

def event name = DEFAULT_TARGET, &block
  global_registry.add_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) 


136
137
138
139
 
# File 'lib/functions_framework.rb', line 136

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:

  • target (String) —

    The name of the function to run

Yields:

Returns:

  • (self) 


231
232
233
234
235
 
# File 'lib/functions_framework.rb', line 231

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:

  • target (String) —

    The name of the function to run

Yields:

Returns:

Raises:

  • (::ArgumentError) 


213
214
215
216
217
218
219
220
 
# File 'lib/functions_framework.rb', line 213

def start target, &block
  require "functions_framework/server"
  function = global_registry[target]
  raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
  server = Server.new function, &block
  server.respond_to_signals
  server.start
end