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-rubyexecutable. 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-rubyexecutable 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
+ + +
+ "0.10.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.
+ + +
+ "function".freeze
+
+ - DEFAULT_SOURCE =
+ ++ +++
The default source file path. The CLI loads functions from this file if no +source file is given explicitly.
+ + +
+ "./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
+-
+
+
-
+
+
+ .global_registry ⇒ FunctionsFramework::Registry
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
The "global" registry that holds events defined by the FunctionsFramework class methods.
+
+
+
+ -
+
+
+ .logger ⇒ Logger
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
A "global" logger that is used by the framework's web server, and can also be used by functions.
+
+
+
+
+ Class Method Summary + collapse +
+ +-
+
+
-
+
+
+ .cloud_event(name = DEFAULT_TARGET, &block) ⇒ self
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
Define a function that responds to CloudEvents.
+
+
+
+ -
+
+
+ .http(name = DEFAULT_TARGET, &block) ⇒ self
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
Define a function that response to HTTP requests.
+
+
+
+ -
+
+
+ .on_startup(&block) ⇒ self
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
Define a server startup task.
+
+
+
+ -
+
+
+ .run(target) {|FunctionsFramework::Server::Config| ... } ⇒ self
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
Run the functions framework server and block until it stops.
+
+
+
+ -
+
+
+ .start(target) {|FunctionsFramework::Server::Config| ... } ⇒ FunctionsFramework::Server
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + +
Run startup tasks, then start the functions framework server in the background.
+
+
+
+
Class Attribute Details
+ + + ++ + .global_registry ⇒ FunctionsFramework::Registry + + + + + +
The "global" registry that holds events defined by the +FunctionsFramework class methods.
+ + +
+ + + +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.
+ + +
+ + + +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
+
+ + + +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::Responseobject.
+ - 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
+
+ + + +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.
+ + +
+ + + +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.
+ + +
+ + + +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.
+ + +
+ + + +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+ |
+