functions_framework 0.1.0

data/lib/functions_framework.rb

@@ -0,0 +1,237 @@
+# 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 "logger"
+
+require "functions_framework/cloud_events"
+require "functions_framework/function"
+require "functions_framework/registry"
+require "functions_framework/version"
+
+##
+# 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

data/lib/functions_framework/cli.rb

@@ -0,0 +1,113 @@
+# 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 "optparse"
+
+require "functions_framework"
+
+module FunctionsFramework
+  ##
+  # Implementation of the functions-framework executable.
+  #
+  class CLI
+    ##
+    # Create a new CLI, setting arguments to their defaults.
+    #
+    def initialize
+      @target = ::ENV["FUNCTION_TARGET"] || ::FunctionsFramework::DEFAULT_TARGET
+      @source = ::ENV["FUNCTION_SOURCE"] || ::FunctionsFramework::DEFAULT_SOURCE
+      @env = nil
+      @port = nil
+      @bind = nil
+      @min_threads = nil
+      @max_threads = nil
+      @detailed_errors = nil
+    end
+
+    ##
+    # Parse the given command line arguments.
+    # Exits if argument parsing failed.
+    #
+    # @param argv [Array<String>]
+    # @return [self]
+    #
+    def parse_args argv # rubocop:disable Metrics/MethodLength
+      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|
+          @target = val
+        end
+        op.on "-s", "--source SOURCE",
+              "Set the source file to load (defaults to #{DEFAULT_SOURCE})" do |val|
+          @source = val
+        end
+        op.on "-p", "--port PORT", "Set the port to listen to (defaults to 8080)" do |val|
+          @port = val.to_i
+        end
+        op.on "-b", "--bind BIND", "Set the address to bind to (defaults to 0.0.0.0)" do |val|
+          @bind = val
+        end
+        op.on "-e", "--environment ENV", "Set the Rack environment" do |val|
+          @env = val
+        end
+        op.on "--min-threads NUM", "Set the minimum threead pool size" do |val|
+          @min_threads = val
+        end
+        op.on "--max-threads NUM", "Set the maximum threead pool size" do |val|
+          @max_threads = val
+        end
+        op.on "--[no-]detailed-errors", "Set whether to show error details" do |val|
+          @detailed_errors = val
+        end
+        op.on "-v", "--verbose", "Increase log verbosity" do
+          ::FunctionsFramework.logger.level -= 1
+        end
+        op.on "-q", "--quiet", "Decrease log verbosity" do
+          ::FunctionsFramework.logger.level += 1
+        end
+        op.on "--help", "Display help" do
+          puts op
+          exit
+        end
+      end
+      option_parser.parse! argv
+      unless argv.empty?
+        warn "Unrecognized arguments: #{argv}"
+        puts op
+        exit 1
+      end
+      self
+    end
+
+    ##
+    # Run the configured server, and block until it stops.
+    # @return [self]
+    #
+    def run
+      FunctionsFramework.logger.info \
+        "FunctionsFramework: Loading functions from #{@source.inspect}..."
+      load @source
+      server = ::FunctionsFramework.start @target do |config|
+        config.rack_env = @env
+        config.port = @port
+        config.bind_addr = @bind
+        config.show_error_details = @detailed_errors
+        config.min_threads = @min_threads
+        config.max_threads = @max_threads
+      end
+      server.wait_until_stopped
+      self
+    end
+  end
+end

data/lib/functions_framework/cloud_events.rb

@@ -0,0 +1,143 @@
+# 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 "functions_framework/cloud_events/binary_content"
+require "functions_framework/cloud_events/content_type"
+require "functions_framework/cloud_events/event"
+
+module FunctionsFramework
+  ##
+  # CloudEvents implementation.
+  #
+  # This is a Ruby implementation of the [CloudEvents](https://cloudevents.io)
+  # [1.0 specification](https://github.com/cloudevents/spec/blob/master/spec.md).
+  # It provides for unmarshaling of events from Rack environment data from
+  # binary (i.e. header-based) format, as well as structured (body-based) and
+  # batch formats. A standard JSON structure parser is included. It is also
+  # possible to register handlers for other formats.
+  #
+  # TODO: Unmarshaling of events is implemented, but marshaling is not.
+  #
+  module CloudEvents
+    @structured_formats = {}
+    @batched_formats = {}
+
+    class << self
+      ##
+      # Register a handler for the given structured format.
+      # The handler object must respond to the method
+      # `#decode_structured_content`. See
+      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
+      #
+      # @param format [String] The subtype format that should be handled by
+      #     this handler
+      # @param handler [#decode_structured_content] The handler object
+      # @return [self]
+      #
+      def register_structured_format format, handler
+        handlers = @structured_formats[format.to_s.strip.downcase] ||= []
+        handlers << handler unless handlers.include? handler
+        self
+      end
+
+      ##
+      # Register a handler for the given batched format.
+      # The handler object must respond to the method
+      # `#decode_batched_content`. See
+      # {FunctionsFramework::CloudEvents::JsonStructure} for an example.
+      #
+      # @param format [String] The subtype format that should be handled by
+      #     this handler
+      # @param handler [#decode_batched_content] The handler object
+      # @return [self]
+      #
+      def register_batched_format format, handler
+        handlers = @batched_formats[format.to_s.strip.downcase] ||= []
+        handlers << handler unless handlers.include? handler
+        self
+      end
+
+      ##
+      # Decode an event from the given Rack environment hash. Following the
+      # CloudEvents spec, this chooses a handler based on the Content-Type of
+      # the request.
+      #
+      # @param env [Hash] The Rack environment
+      # @return [FunctionsFramework::CloudEvents::Event] if the request
+      #     includes a single structured or binary event
+      # @return [Array<FunctionsFramework::CloudEvents::Event>] if the request
+      #     includes a batch of structured events
+      #
+      def decode_rack_env env
+        content_type_header = env["CONTENT_TYPE"]
+        raise "Missing content-type header" unless content_type_header
+        content_type = ContentType.new content_type_header
+        if content_type.media_type == "application"
+          case content_type.subtype_prefix
+          when "cloudevents"
+            return decode_structured_content env["rack.input"], content_type
+          when "cloudevents-batch"
+            return decode_batched_content env["rack.input"], content_type
+          end
+        end
+        BinaryContent.decode_rack_env env, content_type
+      end
+
+      ##
+      # Decode a single event from the given content data. This should be
+      # passed the request body, if the Content-Type is of the form
+      # `application/cloudevents+format`.
+      #
+      # @param input [IO] An IO-like object providing the content
+      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
+      #     content type
+      # @return [FunctionsFramework::CloudEvents::Event]
+      #
+      def decode_structured_content input, content_type
+        handlers = @structured_formats[content_type.subtype_format] || []
+        handlers.reverse_each do |handler|
+          event = handler.decode_structured_content input, content_type
+          return event if event
+        end
+        raise "Unknown cloudevents format: #{content_type.subtype_format.inspect}"
+      end
+
+      ##
+      # Decode a batch of events from the given content data. This should be
+      # passed the request body, if the Content-Type is of the form
+      # `application/cloudevents-batch+format`.
+      #
+      # @param input [IO] An IO-like object providing the content
+      # @param content_type [FunctionsFramework::CloudEvents::ContentType] the
+      #     content type
+      # @return [Array<FunctionsFramework::CloudEvents::Event>]
+      #
+      def decode_batched_content input, content_type
+        handlers = @batched_formats[content_type.subtype_format] || []
+        handlers.reverse_each do |handler|
+          events = handler.decode_batched_content input, content_type
+          return events if events
+        end
+        raise "Unknown cloudevents batch format: #{content_type.subtype_format.inspect}"
+      end
+    end
+  end
+end
+
+require "functions_framework/cloud_events/json_structure"
+
+FunctionsFramework::CloudEvents.register_structured_format \
+  "json", FunctionsFramework::CloudEvents::JsonStructure
+FunctionsFramework::CloudEvents.register_batched_format \
+  "json", FunctionsFramework::CloudEvents::JsonStructure