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/errors.rb,
lib/functions_framework/cloud_events/event/v1.rb,
lib/functions_framework/legacy_event_converter.rb,
lib/functions_framework/cloud_events/json_format.rb,
lib/functions_framework/cloud_events/content_type.rb,
lib/functions_framework/cloud_events/http_binding.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-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.

  • 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-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: CloudEvents, Testing Classes: CLI, Function, LegacyEventConverter, Registry, Server

Constant Summary collapse

VERSION =

Version of the Ruby Functions Framework

Returns:

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



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

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) 


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

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.

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) 


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

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

.event(name = DEFAULT_TARGET, &block) ⇒ Object

Deprecated.

Use cloud_event instead.

This is an obsolete interface that defines an event function taking two arguments (data and context) rather than one.



148
149
150
151
 
# File 'lib/functions_framework.rb', line 148

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) 


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

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) 


208
209
210
211
212
 
# File 'lib/functions_framework.rb', line 208

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:



185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/functions_framework.rb', line 185

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