functions_framework 0.0.0 → 0.1.0

data/lib/functions_framework/testing.rb

@@ -0,0 +1,244 @@
+# Copyright 2020 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 "json"
+
+require "rack"
+
+require "functions_framework"
+
+module FunctionsFramework
+  ##
+  # Helpers for writing unit tests.
+  #
+  # Methods on this module can be called as module methods, or this module can
+  # be included in a test class.
+  #
+  # ## Example
+  #
+  # Suppose we have the following app that uses the functions framework:
+  #
+  #     # app.rb
+  #
+  #     require "functions_framework"
+  #
+  #     FunctionsFramework.http "my-function" do |request|
+  #       "Hello, world!"
+  #     end
+  #
+  # The following is a test that could be run against that app:
+  #
+  #     # test_app.rb
+  #
+  #     require "minitest/autorun"
+  #     require "functions_framework/testing"
+  #
+  #     class MyTest < Minitest::Test
+  #       # Make the testing methods available.
+  #       include FunctionsFramework::Testing
+  #
+  #       def test_my_function
+  #         # Load app.rb and apply its functions within this block
+  #         load_temporary "app.rb" do
+  #           # Create a mock http (rack) request
+  #           request = make_get_request "http://example.com"
+  #
+  #           # Call the function and get a rack response
+  #           response = call_http "my-function", request
+  #
+  #           # Assert against the response
+  #           assert_equal "Hello, world!", response.body.join
+  #         end
+  #       end
+  #     end
+  #
+  module Testing
+    ##
+    # Load the given functions source for the duration of the given block,
+    # and restore the previous status afterward.
+    #
+    # @param path [String] File path to load
+    #
+    def load_temporary path
+      registry = ::FunctionsFramework::Registry.new
+      old_registry = ::FunctionsFramework.global_registry
+      ::FunctionsFramework.global_registry = registry
+      begin
+        ::Kernel.load path
+        yield
+      ensure
+        ::FunctionsFramework.global_registry = old_registry
+      end
+    end
+
+    ##
+    # Call the given HTTP function for testing. The underlying function must
+    # be of type `:http`.
+    #
+    # @param name [String] The name of the function to call
+    # @param request [Rack::Request] The Rack request to send
+    # @return [Rack::Response]
+    #
+    def call_http name, request
+      function = ::FunctionsFramework.global_registry[name]
+      case function&.type
+      when :http
+        Testing.interpret_response { function.call request }
+      when nil
+        raise "Unknown function name #{name}"
+      else
+        raise "Function #{name} is not an HTTP function"
+      end
+    end
+
+    ##
+    # Call the given event function for testing. The underlying function must
+    # be of type `:event` or `:cloud_event`.
+    #
+    # @param name [String] The name of the function to call
+    # @param event [FunctionsFramework::CloudEvets::Event] The event to send
+    # @return [nil]
+    #
+    def call_event name, event
+      function = ::FunctionsFramework.global_registry[name]
+      case function&.type
+      when :event, :cloud_event
+        function.call event
+        nil
+      when nil
+        raise "Unknown function name #{name}"
+      else
+        raise "Function #{name} is not a CloudEvent function"
+      end
+    end
+
+    ##
+    # Make a simple GET request, for passing to a function test.
+    #
+    # @param url [URI,String] The URL to get.
+    # @return [Rack::Request]
+    #
+    def make_get_request url, headers = []
+      env = Testing.build_standard_env URI(url), headers
+      env[::Rack::REQUEST_METHOD] = ::Rack::GET
+      ::Rack::Request.new env
+    end
+
+    ##
+    # Make a simple POST request, for passing to a function test.
+    #
+    # @param url [URI,String] The URL to post to.
+    # @param data [String] The body to post.
+    # @return [Rack::Request]
+    #
+    def make_post_request url, data, headers = []
+      env = Testing.build_standard_env URI(url), headers
+      env[::Rack::REQUEST_METHOD] = ::Rack::POST
+      env[::Rack::INPUT_STREAM] = ::StringIO.new data
+      ::Rack::Request.new env
+    end
+
+    ##
+    # Make a simple CloudEvent, for passing to a function test. The event data
+    # is required, but all other parameters are optional (i.e. a reasonable or
+    # random value will be generated if not provided).
+    #
+    # @param data [Object] The data
+    # @param id [String] Event ID (optional)
+    # @param source [String,URI] Event source (optional)
+    # @param type [String] Event type (optional)
+    # @param spec_version [String] Spec version (optional)
+    # @param data_content_type [String,FunctionsFramework::CloudEvents::ContentType]
+    #     Content type for the data (optional)
+    # @param data_schema [String,URI] Data schema (optional)
+    # @param subject [String] Subject (optional)
+    # @param time [String,DateTime] Event timestamp (optional)
+    # @return [FunctionsFramework::CloudEvents::Event]
+    #
+    def make_cloud_event data,
+                         id: nil, source: nil, type: nil, spec_version: nil,
+                         data_content_type: nil, data_schema: nil, subject: nil, time: nil
+      id ||= "random-id-#{rand 100_000_000}"
+      source ||= "functions-framework-testing"
+      type ||= "com.example.test"
+      spec_version ||= "1.0"
+      CloudEvents::Event.new id: id, source: source, type: type, spec_version: spec_version,
+                             data_content_type: data_content_type, data_schema: data_schema,
+                             subject: subject, time: time, data: data
+    end
+
+    extend self
+
+    class << self
+      ## @private
+      def interpret_response
+        response =
+          begin
+            yield
+          rescue ::StandardError => e
+            e
+          end
+        case response
+        when ::Rack::Response
+          response
+        when ::Array
+          ::Rack::Response.new response[2], response[0], response[1]
+        when ::String
+          string_response response, "text/plain", 200
+        when ::Hash
+          json = ::JSON.dump response
+          string_response json, "application/json", 200
+        when ::StandardError
+          message = "#{response.class}: #{response.message}\n#{response.backtrace}\n"
+          string_response message, "text/plain", 500
+        else
+          raise "Unexpected response type: #{response.inspect}"
+        end
+      end
+
+      ## @private
+      def string_response string, content_type, status
+        headers = {
+          "Content-Type"   => content_type,
+          "Content-Length" => string.bytesize
+        }
+        ::Rack::Response.new string, status, headers
+      end
+
+      ## @private
+      def build_standard_env url, headers
+        env = {
+          ::Rack::SCRIPT_NAME     => "",
+          ::Rack::PATH_INFO       => url.path,
+          ::Rack::QUERY_STRING    => url.query,
+          ::Rack::SERVER_NAME     => url.host,
+          ::Rack::SERVER_PORT     => url.port,
+          ::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
+        }
+        headers.each do |header|
+          name, value = header.split ":"
+          next unless name && value
+          name = name.strip.upcase.tr "-", "_"
+          name = "HTTP_#{name}" unless ["CONTENT_TYPE", "CONTENT_LENGTH"].include? name
+          env[name] = value.strip
+        end
+        env
+      end
+    end
+  end
+end

data/lib/functions_framework/version.rb

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

data/lib/functions_framework.rb

@@ -12,10 +12,226 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "logger"
+
+require "functions_framework/cloud_events"
+require "functions_framework/function"
+require "functions_framework/registry"
 require "functions_framework/version"
 
 ##
-# The Functions Framework for Ruby
+# The Functions Framework for Ruby.
+#
+# Functions Framework is an open source framework for writing lightweight,
+# portable Ruby functions that run in a serverless environment. For general
+# information about the Functions Framework, see
+# https://github.com/GoogleCloudPlatform/functions-framework.
+# To get started with the functions framework for Ruby, see
+# https://github.com/GoogleCloudPlatform/functions-framework-ruby for basic
+# examples.
+#
+# ## Inside the FunctionsFramework module
+#
+# The FunctionsFramework module includes the main entry points for the
+# functions framework. Use the {FunctionsFramework.http},
+# {FunctionsFramework.event}, or {FunctionsFramework.cloud_event} methods to
+# define functions. To serve functions via a web service, invoke the
+# `functions-framework` executable, or use the {FunctionsFramework.start} or
+# {FunctionsFramework.run} methods.
+#
+# ## Internal modules
+#
+# Here is a roadmap to the internal modules in the Ruby functions framework.
+#
+#  *  {FunctionsFramework::CloudEvents} provides an implementation of the
+#     [CloudEvents](https://cloudevents.io) specification. In particular, if
+#     you define an event function, you will receive the event as a
+#     {FunctionsFramework::CloudEvents::Event} object.
+#  *  {FunctionsFramework::CLI} is the implementation of the
+#     `functions-framework` executable. Most apps will not need to interact
+#     with this class directly.
+#  *  {FunctionsFramework::Function} is the internal representation of a
+#     function, indicating the type of function (http or cloud event), the
+#     name of the function, and the block of code implementing it. Most apps
+#     do not need to interact with this class directly.
+#  *  {FunctionsFramework::Registry} looks up functions by name. When you
+#     define a set of named functions, they are added to a registry, and when
+#     you start a server and specify the target function by name, it is looked
+#     up from the registry. Most apps do not need to interact with this class
+#     directly.
+#  *  {FunctionsFramework::Server} is a web server that makes a function
+#     available via HTTP. It wraps the Puma web server and runs a specific
+#     {FunctionsFramework::Function}. Many apps can simply run the
+#     `functions-framework` executable to spin up a server. However, if you
+#     need closer control over your execution environment, you can use the
+#     {FunctionsFramework::Server} class to run a server. Note that, in most
+#     cases, it is easier to use the {FunctionsFramework.start} or
+#     {FunctionsFramework.run} wrapper methods rather than instantiate a
+#     {FunctionsFramework::Server} class directly.
+#  *  {FunctionsFramework::Testing} provides helpers that are useful when
+#     writing unit tests for functions.
 #
 module FunctionsFramework
+  @global_registry = Registry.new
+  @logger = ::Logger.new ::STDERR
+  @logger.level = ::Logger::INFO
+
+  ##
+  # The default target function name. If you define a function without
+  # specifying a name, or run the framework without giving a target, this name
+  # is used.
+  #
+  # @return [String]
+  #
+  DEFAULT_TARGET = "function".freeze
+
+  ##
+  # The default source file path. The CLI loads functions from this file if no
+  # source file is given explicitly.
+  #
+  # @return [String]
+  #
+  DEFAULT_SOURCE = "./app.rb".freeze
+
+  class << self
+    ##
+    # The "global" registry that holds events defined by the
+    # {FunctionsFramework} class methods.
+    #
+    # @return [FunctionsFramework::Registry]
+    #
+    attr_accessor :global_registry
+
+    ##
+    # A "global" logger that is used by the framework's web server, and can
+    # also be used by functions.
+    #
+    # @return [Logger]
+    #
+    attr_accessor :logger
+
+    ##
+    # Define a function that response to HTTP requests.
+    #
+    # You must provide a name for the function, and a block that implemets 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
+    #     https://github.com/rack/rack/blob/master/SPEC
+    #  *  A `Rack::Response` object.
+    #  *  A simple String that will be sent as the response body.
+    #  *  A Hash object that will be encoded as JSON and sent as the response
+    #     body.
+    #
+    # ## Example
+    #
+    #     FunctionsFramework.http "my-function" do |request|
+    #       "I received a request for #{request.url}"
+    #     end
+    #
+    # @param name [String] The function name. Defaults to {DEFAULT_TARGET}.
+    # @param block [Proc] The function code as a proc.
+    # @return [self]
+    #
+    def http name = DEFAULT_TARGET, &block
+      global_registry.add_http name, &block
+      self
+    end
+
+    ##
+    # Define a function that responds to CloudEvents.
+    #
+    # You must provide a name for the function, and a block that implemets the
+    # function. The block should take two arguments: the event _data_ and the
+    # event _context_. Any return value is ignored.
+    #
+    # The event data argument will be one of the following types:
+    #  *  A `String` (with encoding `ASCII-8BIT`) if the data is in the form of
+    #     binary data. You may choose to perform additional interpretation of
+    #     the binary data using information in the content type provided by the
+    #     context argument.
+    #  *  Any data type that can be represented in JSON (i.e. `String`,
+    #     `Integer`, `Array`, `Hash`, `true`, `false`, or `nil`) if the event
+    #     came with a JSON payload. The content type may also be set in the
+    #     context if the data is a String.
+    #
+    # The context argument will be of type {FunctionsFramework::CloudEvents::Event},
+    # and will contain CloudEvents context attributes such as `id` and `type`.
+    #
+    # See also {FunctionsFramework.cloud_event} which defines a function that
+    # takes a single argument of type {FunctionsFramework::CloudEvents::Event}.
+    #
+    # ## Example
+    #
+    #     FunctionsFramework.event "my-function" do |data, context|
+    #       FunctionsFramework.logger.info "Event data: #{data.inspect}"
+    #     end
+    #
+    # @param name [String] The function name. Defaults to {DEFAULT_TARGET}.
+    # @param block [Proc] The function code as a proc.
+    # @return [self]
+    #
+    def event name = DEFAULT_TARGET, &block
+      global_registry.add_event name, &block
+      self
+    end
+
+    ##
+    # Define a function that responds to CloudEvents.
+    #
+    # You must provide a name for the function, and a block that implemets the
+    # function. The block should take _one_ argument: the event object of type
+    # {FunctionsFramework::CloudEvents::Event}. Any return value is ignored.
+    #
+    # See also {FunctionsFramework.event} which creates a function that takes
+    # data and context as separate arguments.
+    #
+    # ## Example
+    #
+    #     FunctionsFramework.cloud_event "my-function" do |event|
+    #       FunctionsFramework.logger.info "Event data: #{event.data.inspect}"
+    #     end
+    #
+    # @param name [String] The function name. Defaults to {DEFAULT_TARGET}.
+    # @param block [Proc] The function code as a proc.
+    # @return [self]
+    #
+    def cloud_event name = DEFAULT_TARGET, &block
+      global_registry.add_cloud_event name, &block
+      self
+    end
+
+    ##
+    # Start the functions framework server in the background. The server will
+    # look up the given target function name in the global registry.
+    #
+    # @param target [String] The name of the function to run
+    # @yield [FunctionsFramework::Server::Config] A config object that can be
+    #     manipulated to configure the server.
+    # @return [FunctionsFramework::Server]
+    #
+    def start target, &block
+      require "functions_framework/server"
+      function = global_registry[target]
+      raise ::ArgumentError, "Undefined function: #{target.inspect}" if function.nil?
+      server = Server.new function, &block
+      server.respond_to_signals
+      server.start
+    end
+
+    ##
+    # Run the functions framework server and block until it stops. The server
+    # will look up the given target function name in the global registry.
+    #
+    # @param target [String] The name of the function to run
+    # @yield [FunctionsFramework::Server::Config] A config object that can be
+    #     manipulated to configure the server.
+    # @return [self]
+    #
+    def run target, &block
+      server = start target, &block
+      server.wait_until_stopped
+      self
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: functions_framework
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-12 00:00:00.000000000 Z
+date: 2020-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puma
@@ -139,16 +139,27 @@ dependencies:
 description: The Functions Framework implementation for Ruby.
 email:
 - dazuma@google.com
-executables: []
+executables:
+- functions-framework
 extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
 - CHANGELOG.md
-- CONTRIBUTING.md
 - LICENSE
 - README.md
+- bin/functions-framework
 - lib/functions_framework.rb
+- lib/functions_framework/cli.rb
+- lib/functions_framework/cloud_events.rb
+- lib/functions_framework/cloud_events/binary_content.rb
+- lib/functions_framework/cloud_events/content_type.rb
+- lib/functions_framework/cloud_events/event.rb
+- lib/functions_framework/cloud_events/json_structure.rb
+- lib/functions_framework/function.rb
+- lib/functions_framework/registry.rb
+- lib/functions_framework/server.rb
+- lib/functions_framework/testing.rb
 - lib/functions_framework/version.rb
 homepage: https://github.com/GoogleCloudPlatform/functions-framework-ruby
 licenses:

data/CONTRIBUTING.md

@@ -1,32 +0,0 @@
-# Contributing
-
-Want to contribute? Great! First, read this page (including the small print at the end).
-
-### Before you contribute
-
-Before we can use your code, you must sign the
-[Google Individual Contributor License Agreement]
-(https://cla.developers.google.com/about/google-individual)
-(CLA), which you can do online. The CLA is necessary mainly because you own the
-copyright to your changes, even after your contribution becomes part of our
-codebase, so we need your permission to use and distribute your code. We also
-need to be sure of various other things—for instance that you'll tell us if you
-know that your code infringes on other people's patents. You don't have to sign
-the CLA until after you've submitted your code for review and a member has
-approved it, but you must do it before we can put your code into our codebase.
-Before you start working on a larger contribution, you should get in touch with
-us first through the issue tracker with your idea so that we can help out and
-possibly guide you. Coordinating up front makes it much easier to avoid
-frustration later on.
-
-### Code reviews
-
-All submissions, including submissions by project members, require review. We
-use Github pull requests for this purpose.
-
-### The small print
-
-Contributions made by corporations are covered by a different agreement than
-the one above, the
-[Software Grant and Corporate Contributor License Agreement]
-(https://cla.developers.google.com/about/google-corporate).