functions_framework 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c6958234b00d6168c6756c7188b698d84984628d1ff6a1fcd3bbd46fbb6a876
-  data.tar.gz: 5ec49e5ea07c8416ac04a336a8581cf71d26c4b2fd1048d4dc35db3e7c497bbc
+  metadata.gz: 57eed57ea92eee1e51f3285c883f0f757a87f8379b7316fe5cd1eed46e1782fc
+  data.tar.gz: c039b2139d3692727dffcbe715b390460445d4c8b5728e2c4fbe2c59db3030c8
 SHA512:
-  metadata.gz: 66f952df1cc33a829a48454a49508d56c8b5026e4b145cb0931c04801b85b5f5b6109d8564c54bbf2fa34bc3882d0adc6f944e22af07547de1743b5ac3a824b3
-  data.tar.gz: 81406729506f55f2ca5da840245f4323ca705022f877a31e28af22c41e679d5ea92f40dfca523b3e8c2a869225f5f5abe5a29aa5ff12e5e6ff0a6e9e7e0d9bea
+  metadata.gz: d1369b3334e1605956829e6077fe7d76f5f49155985598d2098928cc6a54d4f58b1252f8e6971cfd3784e104ca15162ec1e37fc0e80f2d0eadf60ad5698d7657
+  data.tar.gz: 9fa3b2e12ff0ad195ad0dd808c147ad30adf9eeb8ac25a2990ebddb11ef8945f80b8091455415cb0462fbc334e3eacc77afeb55175a01a713bbc2f808a3018b8

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 1.4.0 (2023-06-16)
+
+#### Features
+
+* implement typed function signature ([#158](https://github.com/GoogleCloudPlatform/functions-framework-ruby/issues/158)) 
+
 ### 1.3.0 (2023-04-05)
 
 #### Features

data/README.md

@@ -1,4 +1,4 @@
-# Functions Framework for Ruby [![Documentation](https://img.shields.io/badge/docs-FunctionsFramework-red.svg)](https://googlecloudplatform.github.io/functions-framework-ruby/latest) [![Gem Version](https://badge.fury.io/rb/functions_framework.svg)](https://badge.fury.io/rb/functions_framework)
+# Functions Framework for Ruby [![Documentation](https://img.shields.io/badge/docs-FunctionsFramework-red.svg)](https://googlecloudplatform.github.io/functions-framework-ruby/latest) [![Gem Version](https://badge.fury.io/rb/functions_framework.svg)](https://badge.fury.io/rb/functions_framework) ![Security Scorecard](https://api.securityscorecards.dev/projects/github.com/GoogleCloudPlatform/functions-framework-ruby/badge)
 
 An open source framework for writing lightweight, portable Ruby functions that
 run in a serverless environment. Functions written to this Framework will run

data/lib/functions_framework/function.rb

@@ -70,6 +70,23 @@ module FunctionsFramework
       new name, :http, callable: callable, &block
     end
 
+    ##
+    # Create a new Typed function definition.
+    #
+    # @param name [String] The function name
+    # @param callable [Class,#call] A callable object or class.
+    # @param request_class [#decode_json] A class that can be read from JSON.
+    # @param block [Proc] The function code as a block.
+    # @return [FunctionsFramework::Function]
+    #
+    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
+
     ##
     # Create a new CloudEvents function definition.
     #
@@ -102,9 +119,10 @@ module FunctionsFramework
     # @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, request_class: nil, &block
       @name = name
       @type = type
+      @request_class = request_class
       @callable = @callable_class = nil
       if callable.respond_to? :call
         @callable = callable
@@ -129,6 +147,11 @@ module FunctionsFramework
     #
     attr_reader :type
 
+    ##
+    # @return [#decode_json] The class for the request parameter. Only used for typed functions.
+    #
+    attr_reader :request_class
+
     ##
     # Populate the given globals hash with this function's info.
     #

data/lib/functions_framework/registry.rb

@@ -81,6 +81,29 @@ module FunctionsFramework
       self
     end
 
+    ##
+    # Add a Typed function to the registry.
+    #
+    # You must provide a name for the function, and a block that implements the
+    # function. The block should take a single `Hash` argument which will be the
+    # JSON decoded request payload. It should return a `Hash` response which
+    # will be JSON encoded and written to the response.
+    #
+    # @param name [String] The function name.
+    # @param request_class [#decode_json] An optional class which will be used
+    #         to decode the request.
+    # @param block [Proc] The function code as a proc
+    # @return [self]
+    #
+    def add_typed name, request_class: nil, &block
+      name = name.to_s
+      @mutex.synchronize do
+        raise ::ArgumentError, "Function already defined: #{name}" if @functions.key? name
+        @functions[name] = Function.typed name, request_class: request_class, &block
+      end
+      self
+    end
+
     ##
     # Add a CloudEvent function to the registry.
     #

data/lib/functions_framework/server.rb

@@ -54,6 +54,8 @@ module FunctionsFramework
           HttpApp.new function, globals, @config
         when :cloud_event
           EventApp.new function, globals, @config
+        when :typed
+          TypedApp.new function, globals, @config
         else
           raise "Unrecognized function type: #{function.type}"
         end
@@ -405,6 +407,11 @@ module FunctionsFramework
         string_response message, 500
       end
 
+      def bad_request message
+        message = "Bad Request" unless @config.show_error_details?
+        string_response message, 400
+      end
+
       def flush_streams
         $stdout.flush
         $stderr.flush
@@ -436,6 +443,43 @@ module FunctionsFramework
       end
     end
 
+    ## @private
+    class TypedApp < AppBase
+      def initialize function, globals, config
+        super config
+        @function = function
+        @globals = globals
+      end
+
+      def call env
+        return notfound_response if excluded_path? env
+        begin
+          logger = env[::Rack::RACK_LOGGER] ||= @config.logger
+          request = ::Rack::Request.new env
+          logger.info "FunctionsFramework: Handling Typed #{request.request_method} request"
+
+          begin
+            req = if @function.request_class
+                    request_class.decode_json request.body.read.to_s
+                  else
+                    JSON.parse request.body.read.to_s
+                  end
+          rescue JSON::ParserError => e
+            return bad_request e.message
+          end
+
+          res = @function.call req, globals: @globals, logger: logger
+          return string_response res.to_json, 200, content_type: "application/json" if res
+
+          string_response "", 204
+        rescue ::StandardError => e
+          interpret_response e
+        end
+      ensure
+        flush_streams
+      end
+    end
+
     ## @private
     class EventApp < AppBase
       def initialize function, globals, config

data/lib/functions_framework/testing.rb

@@ -134,16 +134,42 @@ module FunctionsFramework
     #
     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.call :http, name, readable_name: "HTTP" do |function|
         Testing.interpret_response do
           function.call request, globals: globals, logger: logger
         end
-      when nil
-        raise "Unknown function name #{name}"
-      else
-        raise "Function #{name} is not an HTTP function"
+      end
+    end
+
+    ##
+    # Call the given Typed function for testing. The underlying function must
+    # be of type `:typed`. 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_typed name, request, globals: nil, logger: nil
+      globals ||= run_startup_tasks name, logger: logger, lenient: true
+      Testing.call :typed, name, readable_name: "Typed" do |function|
+        Testing.interpret_response do
+          config = FunctionsFramework::Server::Config.new
+          config.logger = logger
+          app = FunctionsFramework::Server::TypedApp.new function, globals, config
+          app.call request.env
+        end
       end
     end
 
@@ -169,15 +195,9 @@ module FunctionsFramework
     #
     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
+      Testing.call :cloud_event, name, readable_name: "CloudEvent" do |function|
         function.call event, globals: globals, logger: logger
         nil
-      when nil
-        raise "Unknown function name #{name}"
-      else
-        raise "Function #{name} is not a CloudEvent function"
       end
     end
 
@@ -316,6 +336,20 @@ module FunctionsFramework
         end
       end
 
+      ## @private
+      def call type, name, readable_name: nil
+        readable_name ||= type
+        function = Testing.current_registry[name]
+        case function&.type
+        when type
+          yield function
+        when nil
+          raise "Unknown function name #{name}"
+        else
+          raise "Function #{name} is not a #{readable_name} function"
+        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 = "1.3.0".freeze
+  VERSION = "1.4.0".freeze
 end

data/lib/functions_framework.rb

@@ -115,9 +115,9 @@ module FunctionsFramework
     attr_accessor :logger
 
     ##
-    # Define a function that response to HTTP requests.
+    # Define a function that responds to HTTP requests.
     #
-    # You must provide a name for the function, and a block that implemets the
+    # You must provide a name for the function, and a block that implements 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
@@ -142,10 +142,40 @@ module FunctionsFramework
       self
     end
 
+    ## Define a Typed function that responds to HTTP requests.
+    #
+    # You must provide a name for the function, and a block that implements the
+    # function. The block should take a single argument representing the request
+    # payload. If a `request_type` is provided, the argument object will be of
+    # the given decoded type; otherwise, it will be a JSON hash. The  block
+    # should return a JSON hash or an object that implements `#to_json`.
+    #
+    # ## Example
+    #     FunctionsFramework.typed "my-sum-function" do |add_request|
+    #       {sum: add_request["num1"] + add_response["num2"]}
+    #     end
+    #
+    # ## Example with Type
+    #     FunctionsFramework.typed "identity",
+    #                             request_class: MyCustomType do |custom_type|
+    #       custom_type
+    #     end
+    #
+    # @param name [String] The function name. Defaults to {DEFAULT_TARGET}
+    # @param request_class [#decode_json] An optional class which will be used to
+    #        decode the request if it implements a `decode_json` static method.
+    # @param block [Proc] The function code as a proc @return [self]
+    # @return [self]
+    #
+    def typed name = DEFAULT_TARGET, request_class: nil, &block
+      global_registry.add_typed name, request_class: request_class, &block
+      self
+    end
+
     ##
     # Define a function that responds to CloudEvents.
     #
-    # You must provide a name for the function, and a block that implemets the
+    # You must provide a name for the function, and a block that implements the
     # function. The block should take one argument: the event object of type
     # [`CloudEvents::Event`](https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event).
     # Any return value is ignored.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-06 00:00:00.000000000 Z
+date: 2023-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cloud_events
@@ -106,10 +106,10 @@ homepage: https://github.com/GoogleCloudPlatform/functions-framework-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v1.3.0/file.CHANGELOG.html
+  changelog_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v1.4.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/v1.3.0
+  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v1.4.0
 post_install_message: 
 rdoc_options: []
 require_paths: