functions_framework 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67b0d5e61bb58f49adefbff9794c960438c1577b4e3d54ee5bf072b134834b71
-  data.tar.gz: 9cb295fd8ba39ea9ad5e8eab1c3055eaa18dddef5a1838cc58d7dcdb2d12fc5e
+  metadata.gz: faa749d3b692f754f7ad60dfc3a5b18c2b9b26c757769ab51e16786a6289b4ad
+  data.tar.gz: 8d918a95adc8caa077fdc19fbc1ec3f3b531a6de279b19da2282bbd4479305d5
 SHA512:
-  metadata.gz: 99e58e1511a97dc9e8643a034bc089f5bb4b71d5f842b507151d8728f058a3763b0f55dcd952ac71f212773e6087cb333fcfebb814a33f57cd2057fde09d6272
-  data.tar.gz: e5afdebdc20c069c247e58196d75787a8c3b3e51924b7714851006ade62dc70bce62cd9e42501528103eb41f3ffc2d6239e9dd8c6650798bdbd1693268fa431a
+  metadata.gz: 8e372039d4885f765f634f1f90975282b12c28f97acf7ba9a5ad4dba100a444c5d6a494a8792a9ed2c2fe6cb6f969ee886dab0f26eda8334ebe21288d506413e
+  data.tar.gz: 1f61e76bbc9ba84283e120e77da66dc488ded6178bd07691d42d8c5472605b8d839dd85c75747b3611dfe87bffae3db2d2a4803389ff56fb3b0415f663fce2b3

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+### v0.7.0 / 2020-09-25
+
+* Now requires Ruby 2.5 or later.
+* BREAKING CHANGE: Renamed "context" hash to "globals" and made it read-only for normal functions.
+* BREAKING CHANGE: Server config is no longer passed to startup blocks.
+* ADDED: Provided a "logger" convenience method in the context object.
+* ADDED: Globals can be set from startup blocks, which is useful for initializing shared resources.
+* ADDED: Support for testing startup tasks in the Testing module.
+* ADDED: Support for controlling logging in the Testing module.
+* FIXED: Fixed crash introduced in 0.6.0 when a block didn't declare an expected argument.
+* FIXED: Better support for running concurrent tests.
+* DOCS: Expanded documentation on initialization, execution context, and shared resources.
+* DEPRECATED: The functions-framework executable is deprecated. Use functions-framework-ruby instead.
+
 ### v0.6.0 / 2020-09-17
 
 * ADDED: You can use the --version flag to print the framework version

data/README.md

@@ -42,11 +42,11 @@ requiring an HTTP server or complicated request handling logic.
 
 ## Supported Ruby versions
 
-This library is supported on Ruby 2.4+.
+This library is supported on Ruby 2.5+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.4
+in security maintenance, and not end of life. Currently, this means Ruby 2.5
 and later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
@@ -60,7 +60,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.7"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/bin/functions-framework

@@ -16,4 +16,7 @@
 
 require "functions_framework/cli"
 
+puts "WARNING: The functions-framework executable is deprecated and will be"
+puts "removed in a future version. Please use functions-framework-ruby instead."
+
 ::FunctionsFramework::CLI.new.parse_args(::ARGV).run.complete

data/docs/overview.md

@@ -46,11 +46,11 @@ requiring an HTTP server or complicated request handling logic.
 
 ## Supported Ruby versions
 
-This library is supported on Ruby 2.4+.
+This library is supported on Ruby 2.5+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.4
+in security maintenance, and not end of life. Currently, this means Ruby 2.5
 and later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
@@ -64,7 +64,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.7"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/docs/testing-functions.md

@@ -165,3 +165,53 @@ class MyTest < Minitest::Test
   end
 end
 ```
+
+## Testing startup tasks
+
+When a functions server is starting up, it calls startup tasks automatically.
+In the testing environment, when you call a function using the
+{FunctionsFramework::Testing#call_http} or
+{FunctionsFramework::Testing#call_event} methods, the testing environment will
+also automatically execute any startup tasks for you.
+
+You can also call startup tasks explicitly to test them in isolation, using the
+{FunctionsFramework::Testing#run_startup_tasks} method. Pass the name of a
+function, and the testing module will execute all defined startup blocks, in
+order, as if the server were preparing that function for execution.
+{FunctionsFramework::Testing#run_startup_tasks} returns the resulting globals
+as a hash, so you can assert against its contents.
+
+If you use {FunctionsFramework::Testing#run_startup_tasks} to run the startup
+tasks explicitly, they will not be run again when you call the function itself
+using {FunctionsFramework::Testing#call_http} or
+{FunctionsFramework::Testing#call_event}. However, if startup tasks have
+already been run implicitly by {FunctionsFramework::Testing#call_http} or
+{FunctionsFramework::Testing#call_event}, then attempting to run them again
+explicitly by calling {FunctionsFramework::Testing#run_startup_tasks} will
+result in an exception.
+
+There is currently no way to run a single startup block in isolation. If you
+have multiple startup blocks defined, they are always executed together.
+
+Following is an example test that runs startup tasks explicitly and asserts
+against the effect on the globals.
+
+```ruby
+require "minitest/autorun"
+require "functions_framework/testing"
+
+class MyTest < Minitest::Test
+  include FunctionsFramework::Testing
+
+  def test_startup_tasks
+    load_temporary "app.rb" do
+      globals = run_startup_tasks "my_function"
+      assert_equal "foo", globals[:my_global]
+
+      request = make_get_request "https://example.com/foo"
+      response = call_http "my_function", request
+      assert_equal 200, response.status
+    end
+  end
+end
+```

data/docs/writing-functions.md

@@ -111,7 +111,7 @@ dependency on Sinatra in your `Gemfile`:
 
 ```ruby
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.7"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -197,67 +197,191 @@ FunctionsFramework.http "error_reporter" do |request|
 end
 ```
 
-## Shared resources
-
-Generally, functions should be self-contained and stateless, and should not use
-or share any global state in the Ruby VM. This is because serverless runtimes
-may spin up or terminate instances of your app at any time, and because a
-single instance may be running multiple functions at a time in separate threads.
-
-However, it is sometimes useful to share a resource across multiple function
-invocations that run on the same Ruby instance. For example, you might establish
-a single connection to a remote database or other service, and share it across
-function invocations to avoid incurring the overhead of re-establishing it
-for every function invocation.
-
-When using a shared resource, it is important to keep three things in mind:
-
- 1. **The shared resource should be thread-safe.** This is because serverless
-    runtimes such as Google Cloud Functions may run multiple functions at a time
-    in separate threads.
-
- 2. **Use `FunctionsFramework.on_startup` to initialize shared resources.**
-    Do not initialize a shared resource at the top level of your app. This is
-    because serverless runtimes may load your files (and thus execute any Ruby
-    code at the top level) in a build/deployment environment that may not be
-    equipped to support the resource. Instead, initialize resources in a
-    `FunctionsFramework.on_startup` block, which the Functions Framework will
-    call only just before starting a server.
-
-    For example:
-
-    ```ruby
-    require "functions_framework"
-
-    # This local variable is lexically shared among all blocks.
-    storage_client = nil
-
-    # Do not create the storage client here. This may run during deployment
-    # when, e.g., your storage credentials are not accessible.
-    #   require "google/cloud/storage"
-    #   storage_client = Google::Cloud::Storage.new # <- may fail
-
-    # Use an on_startup block to initialize the shared client.
-    # This block runs only when the framework is starting an actual server,
-    # and is guaranteed to complete before any functions are executed.
-    FunctionsFramework.on_startup do
-      require "google/cloud/storage"
-      storage_client = Google::Cloud::Storage.new
-    end
-
-    # The storage_client is shared among all function invocations
-    FunctionsFramework.http "storage_example" do |request|
-      bucket = storage_client.bucket "my-bucket"
-      file = bucket.file "path/to/my-file.txt"
-      file.download.to_s
-    end
-    ```
-
- 3. **There is no guaranteed cleanup hook.** The Functions Framework does not
-    provide a guaranteed way to register a cleanup task. You can register a
-    `Kernel.at_exit` task, but remember that it is possible for the Ruby VM to
-    terminate without calling it. It is strongly recommended that you use
-    resources that do not require "cleanup".
+## The runtime environment
+
+A serverless environment may be somewhat different from server-based runtime
+environments you might be used to. Serverless runtimes often provide a simpler
+programming model, transparent scaling, and cost savings, but they do so by
+controlling how your code is managed and executed. The Functions Framework is
+designed around a "functions-as-a-service" (FaaS) paradigm, which runs
+self-contained stateless functions that have an input and a return value. It's
+important to understand what that means for your Ruby code in order to get the
+most out of a cloud serverless product.
+
+For example, multithreading is a core element of the Functions Framework. When
+you write functions, you should assume that multiple executions may be taking
+place concurrently in different threads, and thus you should avoid operations
+that can cause concurrency issues or race conditions. The easiest way to do
+this is to make your functions self-contained and stateless. Avoid global
+variables and don't share mutable data between different function executions.
+
+Additionally, a serverless runtime may throttle the CPU whenever no actual
+function executions are taking place. This lets it reduce the CPU resources
+used (and therefore the cost to you), while keeping your application warmed up
+and ready to respond to new requests quickly. An important implication, though,
+is that you should avoid starting up background threads or processes. They may
+not get any CPU time during periods when your Ruby application is not actually
+executing a function.
+
+In the sections below, we'll discuss a few techniques and features of the
+Functions Framework to help you write Ruby code that fits well into a
+serverless paradigm.
+
+### Startup tasks
+
+It is sometimes useful to perform one-time initialization that applies to many
+function executions, for example to warm up caches, perform precomputation, or
+establish shared remote connections. To run code during initialization, use
+{FunctionsFramework.on_startup} to define a _startup task_.
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.on_startup do |function|
+  # Perform initialization here.
+  require "my_cache"
+  MyCache.warmup
+end
+
+FunctionsFramework.http "hello" do |request|
+  # Initialization will be done by the time a normal function is called.
+end
+```
+
+Startup tasks are run once per Ruby instance, before the framework starts
+receiving requests and executing functions. You can define multiple startup
+tasks, and they will run in order, and are guaranteed to complete before any
+function is executed.
+
+The block is optionally passed the {FunctionsFramework::Function} representing
+the function that will be run. You code can, for example, perform different
+initialization depending on the {FunctionsFramework::Function#name} or
+{FunctionsFramework::Function#type}.
+
+**In most cases, initialization code should live in an `on_startup` block
+instead of at the "top level" of your Ruby file.** This is because some
+serverless runtimes may load your Ruby code at build or deployment time (for
+example, to verify that it properly defines the requested function), and this
+will execute any code present at the top level of the Ruby file. If top-level
+code is long-running or depends on runtime resources or environment variables,
+this could cause the deployment to fail. By performing initialization in an
+`on_startup` block instead, you ensure it will run only when an actual runtime
+server is starting up, not at build/deployment time.
+
+```ruby
+require "functions_framework"
+
+# DO NOT perform initialization here because this could get run at build time.
+#   require "my_cache"
+#   MyCache.warmup
+
+# Instead initialize in an on_startup block, which is executed only when a
+# runtime server is starting up.
+FunctionsFramework.on_startup do
+  # Perform initialization here.
+  require "my_cache"
+  MyCache.warmup
+end
+
+# ...
+```
+
+### The execution context and global data
+
+When your function block executes, the _object context_ (i.e. `self`) is set to
+an instance of {FunctionsFramework::Function::Callable}. Each function
+invocation (including functions that might be running concurrently in separate
+threads) runs within a different instance, to help you avoid having functions
+interfere with each other.
+
+The object context also defines a few methods that may be useful when writing
+your function.
+
+First, you can obtain the logger by calling the
+{FunctionsFramework::Function::Callable#logger} convenience method. This is
+the same logger that is provided by the HTTP request object or by the
+{FunctionsFramework.logger} global method.
+
+Second, you can access global shared data by passing a key to
+{FunctionsFramework::Function::Callable#global}. _Global shared data_ is a set
+of key-value pairs that are available to every function invocation. By default,
+two keys are available to all functions:
+
+ *  `:function_name` whose String value is the name of the running function.
+ *  `:function_type` whose value is either `:http` or `:cloud_event` depending
+    on the type of the running function.
+
+Following is a simple example using the `logger` and `global` methods of the
+context object:
+
+```ruby
+require "functions_framework"
+
+FunctionsFramework.cloud_event "hello" do |event|
+  logger.info "Now running the function called #{global(:function_name)}"
+end
+```
+
+To avoid concurrency issues, global shared data is immutable when executing a
+function. You cannot add or delete keys or change the value of existing keys.
+However, the global data is settable during startup tasks, because startup
+tasks never run concurrently. You can use this feature to initialize shared
+resources, as described below.
+
+Using the global data mechanism is generally preferred over actual Ruby global
+variables, because the Functions Framework can help you avoid concurrent edits.
+Additionally, the framework will isolate the sets of global data associated
+with different sets of functions, which lets you test functions in isolation
+without the tests interfering with one another by writing to global variables.
+
+### Sharing resources
+
+Although functions should generally be self-contained and stateless, it is
+sometimes useful to share certain kinds of resources across multiple function
+invocations that run on the same Ruby instance. For example, you might
+establish a single connection to a remote database or other service, and share
+it across function invocations to avoid incurring the overhead of
+re-establishing it for every function invocation.
+
+The best practice for sharing a resource across function invocations is to
+initialize it in a {FunctionsFramework.on_startup} block, and reference it from
+global shared data. (As discussed above, prefer to initialize shared resources
+in a startup task rather than at the top level of a Ruby file, and prefer using
+the Functions Framework's global data mechanism rather than Ruby's global
+variables.)
+
+Here is a simple example:
+
+```ruby
+require "functions_framework"
+
+# Use an on_startup block to initialize a shared client and store it in
+# the global shared data.
+FunctionsFramework.on_startup do
+  require "google/cloud/storage"
+  set_global :storage_client, Google::Cloud::Storage.new
+end
+
+# The shared storage_client can be accessed by all function invocations
+# via the global shared data.
+FunctionsFramework.http "storage_example" do |request|
+  bucket = global(:storage_client).bucket "my-bucket"
+  file = bucket.file "path/to/my-file.txt"
+  file.download.to_s
+end
+```
+
+Importantly, if you do share a resource across function invocations, make sure
+the resource is thread-safe, so that separate functions running concurrently in
+different threads can access them safely. The API clients provided by Google,
+for example, are thread-safe and can be used concurrently.
+
+Also of note: There is no guaranteed cleanup hook. The Functions Framework does
+not provide a way to register a cleanup task, and we recommend against using
+resources that require explicit "cleanup". This is because serverless runtimes
+may perform CPU throttling, and therefore there may not be an opportunity for
+cleanup tasks to run. (For example, you could register a `Kernel.at_exit` task,
+but the Ruby VM may still terminate without calling it.)
 
 ## Structuring a project
 
@@ -271,12 +395,14 @@ and methods that assist in the function implementation.
 By convention, the "main" Ruby file that defines functions should be called
 `app.rb` and be located at the root of the project. The path to this file is
 sometimes known as the **function source**. The Functions Framework allows you
-to specify an arbitrary source, but suome hosting environments (such as Google
+to specify an arbitrary source, but some hosting environments (such as Google
 Cloud Functions) require it to be `./app.rb`.
 
 A source file can define any number of functions (with distinct names). Each of
 the names is known as a **function target**.
 
+Following is a typical layout for a Functions Framework based project.
+
 ```
 (project directory)
 |
@@ -296,13 +422,16 @@ the names is known as a **function target**.
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.5"
+gem "functions_framework", "~> 0.7"
 ```
 
 ```ruby
 # app.rb
 require "functions_framework"
-require_relative "lib/hello"
+
+FunctionsFramework.on_startup do
+  require_relative "lib/hello"
+end
 
 FunctionsFramework.http "hello" do |request|
   Hello.new(request).build_response

data/lib/functions_framework.rb

@@ -175,10 +175,8 @@ module FunctionsFramework
     # 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 two arguments: the {FunctionsFramework::Function}
-    # identifying the function to execute, and the
-    # {FunctionsFramework::Server::Config} specifying the (frozen) server
-    # configuration. Tasks have no return value.
+    # 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]
@@ -189,8 +187,9 @@ module FunctionsFramework
     end
 
     ##
-    # Start the functions framework server in the background. The server will
-    # look up the given target function name in the global registry.
+    # 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.
@@ -206,8 +205,12 @@ module FunctionsFramework
         function = global_registry[target]
         raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
       end
-      server = Server.new function, &block
-      global_registry.run_startup_tasks server
+      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

data/lib/functions_framework/function.rb

@@ -18,44 +18,91 @@ module FunctionsFramework
   #
   # 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 {FunctionsFramework::Registry.add_http}. For a function of type
-  # `:cloud_event`, the `call` method takes a single
-  # [CloudEvent](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event)
-  # argument, and does not return a value.
-  # See {FunctionsFramework::Registry.add_cloud_event}.
+  # 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 {FunctionsFramework::Registry.add_http}.
+  #  *  For a function of type `:cloud_event`, the `call` method takes a single
+  #     [CloudEvent](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event)
+  #     argument, and does not return a value. See
+  #     {FunctionsFramework::Registry.add_cloud_event}.
+  #  *  For a function of type `:startup_task`, the `call` method takes a
+  #     single {FunctionsFramework::Function} argument, and does not return a
+  #     value. See {FunctionsFramework::Registry.add_startup_task}.
   #
-  # If a callable object is provided directly, its `call` method is invoked for
-  # every function execution. Note that this means it may be called multiple
-  # times concurrently in separate threads.
+  # The implementation can be specified in one of three ways:
   #
-  # Alternately, the implementation may be provided as a class that should be
-  # instantiated to produce a callable object. If a class is provided, it should
-  # either subclass {FunctionsFramework::Function::CallBase} or respond to the
-  # same constructor interface, i.e. accepting arbitrary keyword arguments. A
-  # separate callable object will be instantiated from this class for every
-  # function invocation, so each instance will be used for only one invocation.
+  #  *  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 {FunctionsFramework::Function::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 {FunctionsFramework::Function::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.)
   #
-  # Finally, an implementation can be provided as a block. If a block is
-  # provided, it will be recast as a `call` method in an anonymous subclass of
-  # {FunctionsFramework::Function::CallBase}. Thus, providing a block is really
-  # just syntactic sugar for providing a class. (This means, for example, that
-  # the `return` keyword will work 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 {FunctionsFramework::Function::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.
   #
   class Function
+    ##
+    # Create a new HTTP function definition.
+    #
+    # @param name [String] The function name
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    def self.http name, callable: nil, &block
+      new name, :http, callable: callable, &block
+    end
+
+    ##
+    # Create a new CloudEvents function definition.
+    #
+    # @param name [String] The function name
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    def self.cloud_event name, callable: nil, &block
+      new name, :cloud_event, callable: callable, &block
+    end
+
+    ##
+    # Create a new startup task function definition.
+    #
+    # @param callable [Class,#call] A callable object or class.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    def self.startup_task callable: nil, &block
+      new nil, :startup_task, callable: callable, &block
+    end
+
     ##
     # Create a new function definition.
     #
     # @param name [String] The function name
-    # @param type [Symbol] The type of function. Valid types are `:http` and
-    #     `:cloud_event`.
+    # @param type [Symbol] The type of function. Valid types are `:http`,
+    #     `:cloud_event`, and `:startup_task`.
     # @param callable [Class,#call] A callable object or class.
     # @param block [Proc] The function code as a block.
     #
-    def initialize name, type, callable = nil, &block
+    def initialize name, type, callable: nil, &block
       @name = name
       @type = type
       @callable = @callable_class = nil
@@ -64,7 +111,7 @@ module FunctionsFramework
       elsif callable.is_a? ::Class
         @callable_class = callable
       elsif block_given?
-        @callable_class = ::Class.new CallBase do
+        @callable_class = ::Class.new Callable do
           define_method :call, &block
         end
       else
@@ -83,18 +130,38 @@ module FunctionsFramework
     attr_reader :type
 
     ##
-    # Get a callable for performing a function invocation. This will either
-    # return the singleton callable object, or instantiate a new callable from
-    # the configured class.
-    #
-    # @param logger [::Logger] The logger for use by function executions. This
-    #     may or may not be used by the callable.
-    # @return [#call]
-    #
-    def new_call logger: nil
-      return @callable unless @callable.nil?
-      logger ||= FunctionsFramework.logger
-      @callable_class.new logger: logger, function_name: name, function_type: type
+    # Populate the given globals hash with this function's info.
+    #
+    # @param globals [Hash] Initial globals hash (optional).
+    # @return [Hash] A new globals hash with this function's info included.
+    #
+    def populate_globals globals = nil
+      result = { function_name: name, function_type: type }
+      result.merge! globals if globals
+      result
+    end
+
+    ##
+    # 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.
+    #
+    # @param args [Array] Argument to pass to the function.
+    # @param logger [Logger] Logger for use by function executions.
+    # @param globals [Hash] Globals for the function execution context
+    # @return [Object] The function return value.
+    #
+    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
 
     ##
@@ -102,29 +169,56 @@ module FunctionsFramework
     #
     # An object of this class is `self` while a function block is running.
     #
-    class CallBase
+    class Callable
       ##
       # Create a callable object with the given context.
       #
-      # @param context [keywords] A set of context arguments. See {#context} for
-      #     a list of keys that will generally be passed in. However,
-      #     implementations should be prepared to accept any abritrary keys.
+      # @param globals [Hash] A set of globals available to the call.
+      # @param logger [Logger] A logger for use by the function call.
       #
-      def initialize **context
-        @context = context
+      def initialize globals: nil, logger: nil
+        @__globals = globals || {}
+        @__logger = logger || FunctionsFramework.logger
       end
 
       ##
-      # A keyed hash of context information. Common context keys include:
+      # Get the given named global.
+      #
+      # For most function calls, the following globals will be defined:
       #
-      #  *  **:logger** (`Logger`) A logger for use by this function call.
       #  *  **:function_name** (`String`) The name of the running function.
       #  *  **:function_type** (`Symbol`) The type of the running function,
       #     either `:http` or `:cloud_event`.
       #
-      # @return [Hash]
+      # You can also set additional globals from a startup task.
+      #
+      # @param key [Symbol,String] The name of the global to get.
+      # @return [Object]
       #
-      attr_reader :context
+      def global key
+        @__globals[key]
+      end
+
+      ##
+      # Set a global. This can be called from startup tasks, but the globals
+      # are frozen when the server starts, so this call will raise an exception
+      # if called from a normal function.
+      #
+      # @param key [Symbol,String]
+      # @param value [Object]
+      #
+      def set_global key, value
+        @__globals[key] = value
+      end
+
+      ##
+      # A logger for use by this call.
+      #
+      # @return [Logger]
+      #
+      def logger
+        @__logger
+      end
     end
   end
 end

data/lib/functions_framework/registry.rb

@@ -12,20 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "monitor"
-
 module FunctionsFramework
   ##
   # Registry providing lookup of functions by name.
   #
   class Registry
-    include ::MonitorMixin
-
     ##
     # Create a new empty registry.
     #
     def initialize
-      @mutex = ::Monitor.new
+      @mutex = ::Mutex.new
       @functions = {}
       @start_tasks = []
     end
@@ -51,17 +47,12 @@ module FunctionsFramework
     end
 
     ##
-    # Run all startup tasks.
+    # Return an array of startup tasks.
     #
-    # @param server [FunctionsFramework::Server] The server that is starting.
-    # @return [self]
+    # @return [Array<FunctionsFramework::Function>]
     #
-    def run_startup_tasks server
-      tasks = @mutex.synchronize { @start_tasks.dup }
-      tasks.each do |task|
-        task.call server.function, server.config
-      end
-      self
+    def startup_tasks
+      @mutex.synchronize { @start_tasks.dup }
     end
 
     ##
@@ -85,7 +76,7 @@ module FunctionsFramework
       name = name.to_s
       @mutex.synchronize do
         raise ::ArgumentError, "Function already defined: #{name}" if @functions.key? name
-        @functions[name] = Function.new name, :http, &block
+        @functions[name] = Function.http name, &block
       end
       self
     end
@@ -106,7 +97,7 @@ module FunctionsFramework
       name = name.to_s
       @mutex.synchronize do
         raise ::ArgumentError, "Function already defined: #{name}" if @functions.key? name
-        @functions[name] = Function.new name, :cloud_event, &block
+        @functions[name] = Function.cloud_event name, &block
       end
       self
     end
@@ -115,16 +106,15 @@ module FunctionsFramework
     # Add a startup task.
     #
     # Startup tasks are generally run just before a server starts. They are
-    # passed two arguments: the {FunctionsFramework::Function} identifying the
-    # function to execute, and the {FunctionsFramework::Server::Config}
-    # specifying the (frozen) server configuration. Tasks have no return value.
+    # passed the {FunctionsFramework::Function} identifying the function to
+    # execute, and have no return value.
     #
     # @param block [Proc] The startup task
     # @return [self]
     #
     def add_startup_task &block
       @mutex.synchronize do
-        @start_tasks << block
+        @start_tasks << Function.startup_task(&block)
       end
       self
     end

data/lib/functions_framework/server.rb

@@ -27,17 +27,22 @@ module FunctionsFramework
     include ::MonitorMixin
 
     ##
-    # Create a new web server given a function. Yields a
-    # {FunctionsFramework::Server::Config} object that you can use to set
-    # server configuration parameters. This block is the only opportunity to
-    # set configuration; once the server is initialized, configuration is
-    # frozen.
+    # Create a new web server given a function definition, a set of application
+    # globals, and server configuration.
+    #
+    # To configure the server, pass a block that takes a
+    # {FunctionsFramework::Server::Config} object as the parameter. This block
+    # is the only opportunity to modify the configuration; once the server is
+    # initialized, configuration is frozen.
     #
     # @param function [FunctionsFramework::Function] The function to execute.
+    # @param globals [Hash] Globals to pass to invocations. This hash should
+    #     normally be frozen so separate function invocations cannot interfere
+    #     with one another's globals.
     # @yield [FunctionsFramework::Server::Config] A config object that can be
     #     manipulated to configure this server.
     #
-    def initialize function
+    def initialize function, globals
       super()
       @config = Config.new
       yield @config if block_given?
@@ -46,9 +51,9 @@ module FunctionsFramework
       @app =
         case function.type
         when :http
-          HttpApp.new function, @config
+          HttpApp.new function, globals, @config
         when :cloud_event
-          EventApp.new function, @config
+          EventApp.new function, globals, @config
         else
           raise "Unrecognized function type: #{function.type}"
         end
@@ -379,9 +384,10 @@ module FunctionsFramework
 
     ## @private
     class HttpApp < AppBase
-      def initialize function, config
+      def initialize function, globals, config
         super config
         @function = function
+        @globals = globals
       end
 
       def call env
@@ -391,8 +397,7 @@ module FunctionsFramework
             logger = env["rack.logger"] ||= @config.logger
             request = ::Rack::Request.new env
             logger.info "FunctionsFramework: Handling HTTP #{request.request_method} request"
-            calling_context = @function.new_call logger: logger
-            calling_context.call request
+            @function.call request, globals: @globals, logger: logger
           rescue ::StandardError => e
             e
           end
@@ -402,9 +407,10 @@ module FunctionsFramework
 
     ## @private
     class EventApp < AppBase
-      def initialize function, config
+      def initialize function, globals, config
         super config
         @function = function
+        @globals = globals
         @cloud_events = ::CloudEvents::HttpBinding.default
         @legacy_events = LegacyEventConverter.new
       end
@@ -439,8 +445,7 @@ module FunctionsFramework
 
       def handle_cloud_event event, logger
         logger.info "FunctionsFramework: Handling CloudEvent"
-        calling_context = @function.new_call logger: logger
-        calling_context.call event
+        @function.call event, globals: @globals, logger: logger
         "ok"
       rescue ::StandardError => e
         e

data/lib/functions_framework/testing.rb

@@ -75,19 +75,71 @@ module FunctionsFramework
       Testing.load_for_testing path, &block
     end
 
+    ##
+    # Run startup tasks for the given function name and return the initialized
+    # globals hash.
+    #
+    # Normally, this will be run automatically prior to the first call to the
+    # function using {call_http} or {call_event}, if it has not already been
+    # run. However, you can call it explicitly to test its behavior. It cannot
+    # be called more than once for any given function.
+    #
+    # By default, the {FunctionsFramework.logger} will be used, but you can
+    # override that by providing your own logger. In particular, to disable
+    # logging, you can pass `Logger.new(nil)`.
+    #
+    # @param name [String] The name of the function to start up.
+    # @param logger [Logger] Use the given logger instead of the Functions
+    #     Framework's global logger. Optional.
+    # @param lenient [Boolean] If false (the default), raise an error if the
+    #     given function has already had its startup tasks run. If true,
+    #     duplicate requests to run startup tasks are ignored.
+    # @return [Hash] The initialized globals.
+    #
+    def run_startup_tasks name, logger: nil, lenient: false
+      function = Testing.current_registry[name]
+      raise "Unknown function name #{name}" unless function
+      globals = Testing.current_globals name
+      if globals
+        raise "Function #{name} has already been started up" unless lenient
+      else
+        globals = function.populate_globals
+        Testing.current_registry.startup_tasks.each do |task|
+          task.call function, globals: globals, logger: logger
+        end
+        Testing.current_globals name, globals
+      end
+      globals.freeze
+    end
+
     ##
     # Call the given HTTP function for testing. The underlying function must
-    # be of type `:http`.
+    # be of type `:http`. Returns the Rack response.
+    #
+    # By default, the startup tasks will be run for the given function if they
+    # have not already been run. You can, however, disable running startup
+    # tasks by providing an explicit globals hash.
+    #
+    # By default, the {FunctionsFramework.logger} will be used, but you can
+    # override that by providing your own logger. In particular, to disable
+    # logging, you can pass `Logger.new(nil)`.
     #
     # @param name [String] The name of the function to call
     # @param request [Rack::Request] The Rack request to send
+    # @param globals [Hash] Do not run startup tasks, and instead provide the
+    #     globals directly. Optional.
+    # @param logger [Logger] Use the given logger instead of the Functions
+    #     Framework's global logger. Optional.
     # @return [Rack::Response]
     #
-    def call_http name, request
-      function = ::FunctionsFramework.global_registry[name]
+    def call_http name, request, globals: nil, logger: nil
+      globals ||= run_startup_tasks name, logger: logger, lenient: true
+      function = Testing.current_registry[name]
       case function&.type
       when :http
-        Testing.interpret_response { function.new_call.call request }
+        Testing.interpret_response do
+          function.call request, globals: globals, logger: logger
+        end
       when nil
         raise "Unknown function name #{name}"
       else
@@ -99,15 +151,28 @@ module FunctionsFramework
     # Call the given event function for testing. The underlying function must
     # be of type :cloud_event`.
     #
+    # By default, the startup tasks will be run for the given function if they
+    # have not already been run. You can, however, disable running startup
+    # tasks by providing an explicit globals hash.
+    #
+    # By default, the {FunctionsFramework.logger} will be used, but you can
+    # override that by providing your own logger. In particular, to disable
+    # logging, you can pass `Logger.new(nil)`.
+    #
     # @param name [String] The name of the function to call
     # @param event [::CloudEvents::Event] The event to send
+    # @param globals [Hash] Do not run startup tasks, and instead provide the
+    #     globals directly. Optional.
+    # @param logger [Logger] Use the given logger instead of the Functions
+    #     Framework's global logger. Optional.
     # @return [nil]
     #
-    def call_event name, event
-      function = ::FunctionsFramework.global_registry[name]
+    def call_event name, event, globals: nil, logger: nil
+      globals ||= run_startup_tasks name, logger: logger, lenient: true
+      function = Testing.current_registry[name]
       case function&.type
       when :cloud_event
-        function.new_call.call event
+        function.call event, globals: globals, logger: logger
         nil
       when nil
         raise "Unknown function name #{name}"
@@ -208,27 +273,49 @@ module FunctionsFramework
     extend self
 
     @testing_registries = {}
+    @main_globals = {}
     @mutex = ::Mutex.new
 
     class << self
       ## @private
       def load_for_testing path
         old_registry = ::FunctionsFramework.global_registry
-        @mutex.synchronize do
-          if @testing_registries.key? path
-            ::FunctionsFramework.global_registry = @testing_registries[path]
-          else
-            new_registry = ::FunctionsFramework::Registry.new
-            ::FunctionsFramework.global_registry = new_registry
-            ::Kernel.load path
-            @testing_registries[path] = new_registry
+        ::Thread.current[:functions_framework_testing_registry] =
+          @mutex.synchronize do
+            if @testing_registries.key? path
+              ::FunctionsFramework.global_registry = @testing_registries[path]
+            else
+              new_registry = ::FunctionsFramework::Registry.new
+              ::FunctionsFramework.global_registry = new_registry
+              ::Kernel.load path
+              @testing_registries[path] = new_registry
+            end
           end
-        end
+        ::Thread.current[:functions_framework_testing_globals] = {}
         yield
       ensure
+        ::Thread.current[:functions_framework_testing_registry] = nil
+        ::Thread.current[:functions_framework_testing_globals] = nil
         ::FunctionsFramework.global_registry = old_registry
       end
 
+      ## @private
+      def current_registry
+        ::Thread.current[:functions_framework_testing_registry] ||
+          ::FunctionsFramework.global_registry
+      end
+
+      ## @private
+      def current_globals name, globals = nil
+        name = name.to_s
+        globals_by_name = ::Thread.current[:functions_framework_testing_globals] || @main_globals
+        if globals
+          globals_by_name[name] = globals
+        else
+          globals_by_name[name]
+        end
+      end
+
       ## @private
       def interpret_response
         response =

data/lib/functions_framework/version.rb

@@ -17,5 +17,5 @@ module FunctionsFramework
   # Version of the Ruby Functions Framework
   # @return [String]
   #
-  VERSION = "0.6.0".freeze
+  VERSION = "0.7.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-17 00:00:00.000000000 Z
+date: 2020-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cloud_events
@@ -54,8 +54,8 @@ dependencies:
         version: '2.1'
 description: The Functions Framework is an open source framework for writing lightweight,
   portable Ruby functions that run in a serverless environment. Functions written
-  to this Framework will run Google Cloud Google Cloud Functions, Google Cloud Run,
-  or any other Knative-based environment.
+  to this Framework will run on Google Cloud Functions, Google Cloud Run, or any other
+  Knative-based environment.
 email:
 - dazuma@google.com
 executables:
@@ -87,10 +87,10 @@ homepage: https://github.com/GoogleCloudPlatform/functions-framework-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.6.0/file.CHANGELOG.html
+  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.7.0/file.CHANGELOG.html
   source_code_uri: https://github.com/GoogleCloudPlatform/functions-framework-ruby
   bug_tracker_uri: https://github.com/GoogleCloudPlatform/functions-framework-ruby/issues
-  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.6.0
+  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.7.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -99,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="