module FunctionsFramework
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 github.com/GoogleCloudPlatform/functions-framework. To get started with the functions framework for Ruby, see 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.
* {FunctionsFramework::CLI} is the implementation of the `functions-framework-ruby` executable. Most apps will not need to interact with this class directly. * {FunctionsFramework::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. * {FunctionsFramework::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. * {FunctionsFramework::Server} is a web server that makes a function available via HTTP. It wraps the Puma web server and runs a specific {FunctionsFramework::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 {FunctionsFramework::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 {FunctionsFramework::Server} class directly. * {FunctionsFramework::Testing} provides helpers that are useful when writing unit tests for functions.
Copyright 2020 Google LLC
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Copyright 2020 Google LLC
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Copyright 2020 Google LLC
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Constants
- CloudEvents
The
CloudEvents
implementation was extracted to become the officialCloudEvents
SDK. This alias is left here for backward compatibility.- DEFAULT_SOURCE
The default source file path. The
CLI
loads functions from this file if no source file is given explicitly.@return [String]
- 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.
@return [String]
- VERSION
Version of the Ruby Functions Framework @return [String]
Attributes
The “global” registry that holds events defined by the {FunctionsFramework} class methods.
@return [FunctionsFramework::Registry]
A “global” logger that is used by the framework's web server, and can also be used by functions.
@return [Logger]
Public Class Methods
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`](cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event). Any return value is ignored.
## Example
FunctionsFramework.cloud_event "my-function" do |event| FunctionsFramework.logger.info "Event data: #{event.data.inspect}" end
@param name [String] The function name. Defaults to {DEFAULT_TARGET}. @param block [Proc] The function code as a proc. @return [self]
# File lib/functions_framework.rb, line 163 def cloud_event name = DEFAULT_TARGET, &block global_registry.add_cloud_event name, &block self end
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
@param name [String] The function name. Defaults to {DEFAULT_TARGET}. @param block [Proc] The function code as a proc. @return [self]
# File lib/functions_framework.rb, line 140 def http name = DEFAULT_TARGET, &block global_registry.add_http name, &block self end
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 {FunctionsFramework::Function} identifying the function to execute, and have no return value.
@param block [Proc] The startup task @return [self]
# File lib/functions_framework.rb, line 184 def on_startup &block global_registry.add_startup_task(&block) self end
Run the functions framework server and block until it stops. The server will look up the given target function name in the global registry.
@param target [FunctionsFramework::Function,String] The function to run,
or the name of the function to look up in the global registry.
@yield [FunctionsFramework::Server::Config] A config object that can be
manipulated to configure the server.
@return [self]
# File lib/functions_framework.rb, line 228 def run target, &block server = start target, &block server.wait_until_stopped self end
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.
@param target [FunctionsFramework::Function,String] The function to run,
or the name of the function to look up in the global registry.
@yield [FunctionsFramework::Server::Config] A config object that can be
manipulated to configure the server.
@return [FunctionsFramework::Server]
# 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