functions_framework 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6d562086a839aaf78661b9417d3b931df10c74c98cb07b1710d40d6294b0490
-  data.tar.gz: fd070c121ce3e0c1bab7f1a738178a37c72c5d25c7726d3f3540e687d01bbe25
+  metadata.gz: d313c253cf23573fe55628885064699cf1da8ca51545446cd3a6adf58ffaf3ff
+  data.tar.gz: 2b82761a46c066f2a32af713c85e559afe5fe892bc1c761ec765772dd2633db2
 SHA512:
-  metadata.gz: 478554bfc8b8bafb2efd5bb880b8e053e2442a878bcd1363a4c6ddeab77a811b49530b84f467009b01f2299b70105f17a8a9840d9b35ebbec94359ca14d7114c
-  data.tar.gz: 6873da52a257f542cb782fde59ba7da7f96042f4b69eaf470ea23d81cdb8479e8ff2791a6fbd0fd36ec166039f9718b7ce1b14632c690b44bea2833e280835b5
+  metadata.gz: b58f6f2c3fbebf5cf6c5eb28031a4ec7a389c063b9f2b8edba6b7e346f20683a8a9339202e8075299c67c5a347313c37bd82aac47422981008858e301133cccf
+  data.tar.gz: fbd5515ed316ab193eec32efe17eb66cc937582d1af9b6196854bac8d2dee16de6d0b7429aac66ce287b97043b5dfadc35d989451e7bb3495d62dee512cd1681

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### v0.8.0 / 2021-03-02
+
+* ADDED: Support for lazily-initialized globals
+
 ### v0.7.1 / 2021-01-26
 
 * DOCS: Fixed several errors in the writing-functions doc samples

data/README.md

@@ -60,7 +60,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.7"
+gem "functions_framework", "~> 0.8"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/docs/overview.md

@@ -64,7 +64,7 @@ Create a `Gemfile` listing the Functions Framework as a dependency:
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.7"
+gem "functions_framework", "~> 0.8"
 ```
 
 Create a file called `app.rb` and include the following code. This defines a

data/docs/writing-functions.md

@@ -111,7 +111,7 @@ dependency on Sinatra in your `Gemfile`:
 
 ```ruby
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.7"
+gem "functions_framework", "~> 0.8"
 gem "sinatra", "~> 2.0"
 ```
 
@@ -248,10 +248,10 @@ FunctionsFramework.http "hello" do |request|
 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.
+Startup tasks are run once per Ruby instance during cold start -- that is,
+after the Ruby VM boots up but 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
@@ -286,6 +286,11 @@ end
 # ...
 ```
 
+Because startup tasks run during cold start, they could have an impact on your
+function's startup latency. To mitigate this issue, it is possible to run parts
+of your initialization lazily, as described below in the section below on
+[lazy initialization](#Lazy_initialization).
+
 ### The execution context and global data
 
 When your function block executes, the _object context_ (i.e. `self`) is set to
@@ -331,8 +336,9 @@ 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.
+with different sets of functions, which lets you run functions in isolation
+during unit tests. If you are testing multiple functions, they will not
+interfere with each other as they might if they used global variables.
 
 ### Sharing resources
 
@@ -345,10 +351,10 @@ 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.)
+global shared data. (As discussed above, the best practice is to initialize
+shared resources in a startup task rather than at the top level of a Ruby file,
+and to use the Functions Framework's global data mechanism rather than Ruby's
+global variables.)
 
 Here is a simple example:
 
@@ -383,6 +389,48 @@ 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.)
 
+### Lazy initialization
+
+Because startup tasks run during cold start, they could have an impact on your
+function's startup latency. You can mitigate this by initializing some globals
+_lazily_. When setting a global, instead of computing and setting the value
+directly (e.g. constructing a shared API client object directly), you can
+provide a block that describes how to construct it on demand.
+
+Here is an example using the storage client we saw above.
+
+```ruby
+require "functions_framework"
+
+# This startup block describes _how_ to initialize a shared client, but
+# does not construct it immediately.
+FunctionsFramework.on_startup do
+  require "google/cloud/storage"
+  set_global :storage_client do
+    Google::Cloud::Storage.new
+  end
+end
+
+# The first time this function is invoked, it will call the above block
+# to construct the storage client. Subsequent invocations will not need
+# to construct it again, but will reuse the same shared object.
+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
+```
+
+The block will not be called until a function actually attempts to access the
+global. From that point, subsequent accesses of the global will return that
+same shared value; the block will be called at most once. This is true even if
+multiple functions are run concurrently in different threads.
+
+Lazy initialization is particularly useful if you define several different
+functions that may use different sets of shared resources. Instead of
+initializing all resources eagerly up front, you could initialize them lazily
+and run only the code needed by the function that is actually invoked.
+
 ## Structuring a project
 
 A Functions Framework based "project" or "application" is a typical Ruby
@@ -422,7 +470,7 @@ Following is a typical layout for a Functions Framework based project.
 ```ruby
 # Gemfile
 source "https://rubygems.org"
-gem "functions_framework", "~> 0.7"
+gem "functions_framework", "~> 0.8"
 ```
 
 ```ruby

data/lib/functions_framework/cli.rb

@@ -74,7 +74,7 @@ module FunctionsFramework
     # @param argv [Array<String>]
     # @return [self]
     #
-    def parse_args argv # rubocop:disable Metrics/MethodLength
+    def parse_args argv # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
       @option_parser = ::OptionParser.new do |op| # rubocop:disable Metrics/BlockLength
         op.on "-t", "--target TARGET",
               "Set the name of the function to execute (defaults to #{DEFAULT_TARGET})" do |val|

data/lib/functions_framework/function.rb

@@ -164,6 +164,28 @@ module FunctionsFramework
       callable.call(*args)
     end
 
+    ##
+    # A lazy evaluator for a global
+    # @private
+    #
+    class LazyGlobal
+      def initialize block
+        @block = block
+        @value = nil
+        @mutex = ::Mutex.new
+      end
+
+      def value
+        @mutex.synchronize do
+          if @block
+            @value = @block.call
+            @block = nil
+          end
+          @value
+        end
+      end
+    end
+
     ##
     # A base class for a callable object that provides calling context.
     #
@@ -196,7 +218,9 @@ module FunctionsFramework
       # @return [Object]
       #
       def global key
-        @__globals[key]
+        value = @__globals[key]
+        value = value.value if value.is_a? LazyGlobal
+        value
       end
 
       ##
@@ -204,11 +228,35 @@ module FunctionsFramework
       # 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]
+      # You can set a global to a final value, or you can provide a block that
+      # lazily computes the global the first time it is requested.
+      #
+      # @overload set_global(key, value)
+      #   Set the given global to the given value. For example:
+      #
+      #       set_global(:project_id, "my-project-id")
+      #
+      #   @param key [Symbol,String]
+      #   @param value [Object]
+      #   @return [self]
+      #
+      # @overload set_global(key, &block)
+      #   Call the given block to compute the global's value only when the
+      #   value is actually requested. This block will be called at most once,
+      #   and its result reused for subsequent calls. For example:
+      #
+      #       set_global(:connection_pool) do
+      #         ExpensiveConnectionPool.new
+      #       end
+      #
+      #   @param key [Symbol,String]
+      #   @param block [Proc] A block that lazily computes a value
+      #   @yieldreturn [Object] The value
+      #   @return [self]
       #
-      def set_global key, value
-        @__globals[key] = value
+      def set_global key, value = nil, &block
+        @__globals[key] = block ? LazyGlobal.new(block) : value
+        self
       end
 
       ##

data/lib/functions_framework/legacy_event_converter.rb

@@ -49,16 +49,19 @@ module FunctionsFramework
     end
 
     def normalized_context input
-      raw_context = input["context"]
-      id = raw_context&.[]("eventId") || input["eventId"]
-      timestamp = raw_context&.[]("timestamp") || input["timestamp"]
-      type = raw_context&.[]("eventType") || input["eventType"]
-      service, resource = analyze_resource raw_context&.[]("resource") || input["resource"]
+      id = normalized_context_field input, "eventId"
+      timestamp = normalized_context_field input, "timestamp"
+      type = normalized_context_field input, "eventType"
+      service, resource = analyze_resource normalized_context_field input, "resource"
       service ||= service_from_type type
       return nil unless id && timestamp && type && service && resource
       { id: id, timestamp: timestamp, type: type, service: service, resource: resource }
     end
 
+    def normalized_context_field input, field
+      input["context"]&.[](field) || input[field]
+    end
+
     def analyze_resource raw_resource
       service = resource = nil
       case raw_resource

data/lib/functions_framework/server.rb

@@ -158,7 +158,7 @@ module FunctionsFramework
           ::Signal.trap "SIGHUP" do
             Server.signal_enqueue "SIGHUP", @config.logger, @server
           end
-        rescue ::ArgumentError # rubocop:disable Lint/HandleExceptions
+        rescue ::ArgumentError
           # Not available on all systems
         end
         @signals_installed = true

data/lib/functions_framework/testing.rb

@@ -366,9 +366,10 @@ module FunctionsFramework
           ::Rack::RACK_ERRORS     => ::StringIO.new
         }
         headers.each do |header|
-          if header.is_a? String
+          case header
+          when String
             name, value = header.split ":"
-          elsif header.is_a? Array
+          when ::Array
             name, value = header
           end
           next unless name && value

data/lib/functions_framework/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-26 00:00:00.000000000 Z
+date: 2021-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cloud_events
@@ -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.7.1/file.CHANGELOG.html
+  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.8.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.7.1
+  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v0.8.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -106,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.11
 signing_key: 
 specification_version: 4
 summary: Functions Framework for Ruby