functions_framework 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f26316991786d4688dc35bab52d91d7df30c11fa573b5e5e9678b095d3e2047
-  data.tar.gz: 9b900e5156d42e4acdae4a8312bc25b866202f738f84ed9e264815fb2635ef42
+  metadata.gz: 57eed57ea92eee1e51f3285c883f0f757a87f8379b7316fe5cd1eed46e1782fc
+  data.tar.gz: c039b2139d3692727dffcbe715b390460445d4c8b5728e2c4fbe2c59db3030c8
 SHA512:
-  metadata.gz: 75180c4a931148fff3490084a4a43bacbcc65089812a18b397f9781f4e5e0899db5acde266f27bbf25f325c23d18c987abb4a1671125cb8db049b77da4b05a59
-  data.tar.gz: f7f95a82b95ab9e7b6f4f4dd16f455dac9f3ea71549401b6bc6b781b6b011741f4e9b59ef97fb444c2b0fbec718eb0f8f92895f1a2a7adbd8f404e590c22d124
+  metadata.gz: d1369b3334e1605956829e6077fe7d76f5f49155985598d2098928cc6a54d4f58b1252f8e6971cfd3784e104ca15162ec1e37fc0e80f2d0eadf60ad5698d7657
+  data.tar.gz: 9fa3b2e12ff0ad195ad0dd808c147ad30adf9eeb8ac25a2990ebddb11ef8945f80b8091455415cb0462fbc334e3eacc77afeb55175a01a713bbc2f808a3018b8

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+* Support for Puma 6 and Rack 3
+
 ### 1.2.0 (2022-08-25)
 
 * Update minimum Ruby version to 2.6

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
@@ -82,10 +84,21 @@ module FunctionsFramework
     def start
       synchronize do
         unless running?
-          @server = ::Puma::Server.new @app
-          @server.min_threads = @config.min_threads
-          @server.max_threads = @config.max_threads
-          @server.leak_stack_on_error = @config.show_error_details?
+          # Puma >= 6.0 interprets these settings from options
+          options = {
+            min_threads: @config.min_threads,
+            max_threads: @config.max_threads,
+            environment: @config.show_error_details? ? "development" : "production"
+          }
+          # Puma::Events.stdio for Puma < 6.0; otherwise nil for Puma >= 6.0
+          events = ::Puma::Events.stdio if ::Puma::Events.respond_to? :stdio
+          @server = ::Puma::Server.new @app, events, options
+          if @server.respond_to? :min_threads=
+            # Puma < 6.0 sets server attributes for these settings
+            @server.min_threads = @config.min_threads
+            @server.max_threads = @config.max_threads
+            @server.leak_stack_on_error = @config.show_error_details?
+          end
           @server.binder.add_tcp_listener @config.bind_addr, @config.port
           @config.logger.info "FunctionsFramework: Serving function #{@function.name.inspect} " \
                               "on port #{@config.port}..."
@@ -377,8 +390,8 @@ module FunctionsFramework
           content_type = "#{content_type}; charset=#{string.encoding.name.downcase}"
         end
         headers = {
-          "Content-Type"   => content_type,
-          "Content-Length" => string.bytesize
+          "content-type"   => content_type,
+          "content-length" => string.bytesize
         }
         [status, headers, [string]]
       end
@@ -394,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
@@ -425,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 =
@@ -367,8 +401,8 @@ module FunctionsFramework
           ::Rack::QUERY_STRING    => url.query,
           ::Rack::SERVER_NAME     => url.host,
           ::Rack::SERVER_PORT     => url.port,
+          ::Rack::SERVER_PROTOCOL => "HTTP/1.1",
           ::Rack::RACK_URL_SCHEME => url.scheme,
-          ::Rack::RACK_VERSION    => ::Rack::VERSION,
           ::Rack::RACK_LOGGER     => ::FunctionsFramework.logger,
           ::Rack::RACK_INPUT      => ::StringIO.new,
           ::Rack::RACK_ERRORS     => ::StringIO.new

data/lib/functions_framework/version.rb

@@ -17,5 +17,5 @@ module FunctionsFramework
   # Version of the Ruby Functions Framework
   # @return [String]
   #
-  VERSION = "1.2.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.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-25 00:00:00.000000000 Z
+date: 2023-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cloud_events
@@ -39,7 +39,7 @@ dependencies:
         version: 4.3.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 6.a
+        version: 7.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,21 +49,27 @@ dependencies:
         version: 4.3.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 6.a
+        version: 7.a
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 4.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 4.a
 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 on Google Cloud Functions, Google Cloud Run, or any other
@@ -100,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.2.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.2.0
+  documentation_uri: https://googlecloudplatform.github.io/functions-framework-ruby/v1.4.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -119,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.14
+rubygems_version: 3.4.2
 signing_key: 
 specification_version: 4
 summary: Functions Framework for Ruby