feat: implement typed function signature (#158)

* feat: implement typed function signature

* Implement code review feedback

* added typed signature support to the testing framework

Author: garethgeorge

lib/functions_framework.rb

@@ -115,9 +115,9 @@ class << self
     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 @@ def http name = DEFAULT_TARGET, &block
       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.

lib/functions_framework/function.rb

@@ -70,6 +70,23 @@ def self.http name, callable: nil, &block
       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 @@ def self.startup_task callable: nil, &block
     # @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 @@ def initialize name, type, callable: nil, &block
     #
     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.
     #

lib/functions_framework/registry.rb

@@ -81,6 +81,29 @@ def add_http name, &block
       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.
     #

lib/functions_framework/server.rb

@@ -54,6 +54,8 @@ def initialize function, globals
           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 @@ def error_response message
         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 @@ def call env
       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

lib/functions_framework/testing.rb

@@ -134,16 +134,42 @@ def run_startup_tasks name, logger: nil, lenient: false
     #
     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 @@ def call_http name, request, globals: nil, logger: nil
     #
     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 @@ def current_globals name, globals = nil
         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 =

test/function_definitions/simple_typed.rb

@@ -0,0 +1,23 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "functions_framework"
+
+# Create a simple Typed function called "simple_typed"
+FunctionsFramework.typed "simple_typed" do |request|
+  logger.info "I received a request: #{request['value']}"
+  {
+    value: request["value"] + 1
+  }
+end