Class: FunctionsFramework::Function

Inherits:
Object
  • Object
show all
Defined in:
lib/functions_framework/function.rb

Overview

Representation of a function.

A function has a name, a type, and an implementation.

Function implementations

The implementation in general is an object that responds to the call method.

  • For a function of type :http, the call method takes a single Rack::Request argument and returns one of various HTTP response types. See Registry.add_http.
  • For a function of type :cloud_event, the call method takes a single CloudEvent argument, and does not return a value. See Registry.add_cloud_event.
  • For a function of type :startup_task, the call method takes a single Function argument, and does not return a value. See Registry.add_startup_task.

The implementation can be specified in one of three ways:

  • A callable object can be passed in the callable keyword argument. The object's call method will be invoked for every function execution. Note that this means it may be called multiple times concurrently in separate threads.
  • A callable class can be passed in the callable keyword argument. This class should subclass Callable and define the call method. A separate instance of this class will be created for each function invocation.
  • A block can be provided. It will be used to define the call method in an anonymous subclass of Callable. Thus, providing a block is really just syntactic sugar for providing a class. (This means, for example, that the return keyword will work as expected within the block because it is treated as a method.)

When the implementation is provided as a callable class or block, it is executed in the context of a Callable object. This object provides a convenience accessor for the Logger, and access to globals, which are data defined by the application startup process and available to each function invocation. Typically, globals are used for shared global resources such as service connections and clients.

Defined Under Namespace

Classes: Callable

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, type, callable: nil, request_class: nil, &block) ⇒ Function

Create a new function definition.

Parameters:

  • name (String) —

    The function name

  • type (Symbol) —

    The type of function. Valid types are :http, :cloud_event, and :startup_task.

  • callable (Class, #call) (defaults to: nil) —

    A callable object or class.

  • block (Proc) —

    The function code as a block.



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/functions_framework/function.rb', line 122

def initialize name, type, callable: nil, request_class: nil, &block
  @name = name
  @type = type
  @request_class = request_class
  @callable = @callable_class = nil
  if callable.respond_to? :call
    @callable = callable
  elsif callable.is_a? ::Class
    @callable_class = callable
  elsif block_given?
    @callable_class = ::Class.new Callable do
      define_method :call, &block
    end
  else
    raise ::ArgumentError, "No callable given for function"
  end
end

Instance Attribute Details

#name ⇒ String (readonly)

Returns The function name.

Returns:

  • (String) —

    The function name



143
144
145
 
# File 'lib/functions_framework/function.rb', line 143

def name
  @name
end

#request_class ⇒ #decode_json (readonly)

Returns The class for the request parameter. Only used for typed functions.

Returns:

  • (#decode_json) —

    The class for the request parameter. Only used for typed functions.



153
154
155
 
# File 'lib/functions_framework/function.rb', line 153

def request_class
  @request_class
end

#type ⇒ Symbol (readonly)

Returns The function type.

Returns:

  • (Symbol) —

    The function type



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

def type
  @type
end

Class Method Details

.cloud_event(name, callable: nil, &block) ⇒ FunctionsFramework::Function

Create a new CloudEvents function definition.

Parameters:

  • name (String) —

    The function name

  • callable (Class, #call) (defaults to: nil) —

    A callable object or class.

  • block (Proc) —

    The function code as a block.

Returns:



98
99
100
 
# File 'lib/functions_framework/function.rb', line 98

def self.cloud_event name, callable: nil, &block
  new name, :cloud_event, callable: callable, &block
end

.http(name, callable: nil, &block) ⇒ FunctionsFramework::Function

Create a new HTTP function definition.

Parameters:

  • name (String) —

    The function name

  • callable (Class, #call) (defaults to: nil) —

    A callable object or class.

  • block (Proc) —

    The function code as a block.

Returns:



69
70
71
 
# File 'lib/functions_framework/function.rb', line 69

def self.http name, callable: nil, &block
  new name, :http, callable: callable, &block
end

.startup_task(callable: nil, &block) ⇒ FunctionsFramework::Function

Create a new startup task function definition.

Parameters:

  • callable (Class, #call) (defaults to: nil) —

    A callable object or class.

  • block (Proc) —

    The function code as a block.

Returns:



109
110
111
 
# File 'lib/functions_framework/function.rb', line 109

def self.startup_task callable: nil, &block
  new nil, :startup_task, callable: callable, &block
end

.typed(name, request_class: nil, callable: nil, &block) ⇒ FunctionsFramework::Function

Create a new Typed function definition.

Parameters:

  • name (String) —

    The function name

  • callable (Class, #call) (defaults to: nil) —

    A callable object or class.

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

    A class that can be read from JSON.

  • block (Proc) —

    The function code as a block.

Returns:



82
83
84
85
86
87
88
 
# File 'lib/functions_framework/function.rb', line 82

def self.typed name, request_class: nil, callable: nil, &block
  if request_class && !(request_class.respond_to? :decode_json)
    raise ::ArgumentError, "Type does not implement 'decode_json' class method"
  end

  new name, :typed, callable: callable, request_class: request_class, &block
end

Instance Method Details

#call(*args, globals: nil, logger: nil) ⇒ Object

Call the function given a set of arguments. Set the given logger and/or globals in the context if the callable supports it.

If the given arguments exceeds what the function will accept, the args are silently truncated. However, if the function requires more arguments than are provided, an ArgumentError is raised.

Parameters:

  • args (Array) —

    Argument to pass to the function.

  • logger (Logger) (defaults to: nil) —

    Logger for use by function executions.

  • globals (Hash) (defaults to: nil) —

    Globals for the function execution context

Returns:

  • (Object) —

    The function return value.



180
181
182
183
184
185
186
187
188
 
# File 'lib/functions_framework/function.rb', line 180

def call *args, globals: nil, logger: nil
  callable = @callable || @callable_class.new(globals: globals, logger: logger)
  params = callable.method(:call).parameters.map(&:first)
  unless params.include? :rest
    max_params = params.count(:req) + params.count(:opt)
    args = args.take max_params
  end
  callable.call(*args)
end

#populate_globals(globals = nil) ⇒ Hash

Populate the given globals hash with this function's info.

Parameters:

  • globals (Hash) (defaults to: nil) —

    Initial globals hash (optional).

Returns:

  • (Hash) —

    A new globals hash with this function's info included.



161
162
163
164
165
 
# File 'lib/functions_framework/function.rb', line 161

def populate_globals globals = nil
  result = { function_name: name, function_type: type }
  result.merge! globals if globals
  result
end