functions_framework 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d98d20b3b8e7ab30b0ef44dfee51e6df6ab8f1f2816ee72e50ecaaca099e0fe5
-  data.tar.gz: 1ee993fdaea21fff0c2d6f551d4cea3d67f0ce0264ee0d4fdf6f1c656c7e8211
+  metadata.gz: d09328e219e183d857a5b0e5cbb4a9aac77dcb2b6deea96ecb4909729aac5e46
+  data.tar.gz: 2ffdd21b22c08193b64610ac42ee05f6b5627c25b99ee6d2d45eb52408438e33
 SHA512:
-  metadata.gz: 698ee184e253b7cf071bcf3d1065ed18f06c93e58fae662fbc72ddffa5ea8c92a051d7045fc2afd383f114ac5a46d8d72759eac93b283bd43d4d263c163bd050
-  data.tar.gz: 6bb25e647fc7275311a3dab8cb455214dc58c074d45c5ac17bbf967381d4903e7defeedf74840a5cae045b7d6dc0bd31cbf8e539a8294d43764ec264ec9b94a9
+  metadata.gz: 93cf161a26eee8349e99ec7012698374206e333099c94ecff07609bdefe9f7a33bf331aa3a0b305fd005e0a89ba9988bcc3ed3ce4c2c1edadd587975561b5fe8
+  data.tar.gz: 64eea2572a244dca261c090b6e51445b2f59ad2ad985edb29dc2a52aaa902fd9d9afa44e65e6ca51a6653c16d5532ace49cb9a6defd09c45195d9d81e9238707

data/.yardopts

@@ -7,5 +7,4 @@
 ./lib/functions_framework.rb
 -
 README.md
-CONTRIBUTING.md
 CHANGELOG.md

data/CHANGELOG.md

@@ -1,2 +1,5 @@
 # Changelog
 
+### v0.1.0 / 2020-01-30
+
+* Initial release

data/README.md

@@ -1,12 +1,61 @@
 # Functions Framework
 
+An open source framework for writing lightweight, portable Ruby functions that
+run in a serverless environment. Functions written to this Framework will run
+in many different environments, including:
+
+ *  [Google Cloud Functions](https://cloud.google.com/functions) *(coming soon)*
+ *  [Cloud Run or Cloud Run for Anthos](https://cloud.google.com/run)
+ *  Any other [Knative](https://github.com/knative)-based environment
+ *  Your local development machine
+
+The framework allows you to go from:
+
+```ruby
+FunctionsFramework.http do |request|
+  "Hello, world!\n"
+end
+```
+
+To:
+
+```sh
+curl http://my-url
+# Output: Hello, world!
+```
+
+All without needing to worry about writing an HTTP server or complicated
+request handling logic.
+
+For more information about the Functions Framework, see
+https://github.com/GoogleCloudPlatform/functions-framework
+
+## Features
+
+ *  Define named functions using normal Ruby constructs.
+ *  Invoke functions in response to requests.
+ *  Automatically unmarshal events conforming to the
+    [CloudEvents](https://cloudevents.io) spec.
+ *  Spin up a local development server for quick testing.
+ *  Integrate with standard Ruby libraries such as Rack and Minitest.
+ *  Portable between serverless platforms.
+
 ## Installation
 
+Install the Functions Framework via Rubygems:
+
+```sh
+gem install functions_framework
 ```
-$ gem install functions_framework
+
+Or add it to your Gemfile for installation using Bundler:
+
+```ruby
+# Gemfile
+gem "functions_framework", "~> 0.1"
 ```
 
-## Supported Ruby Versions
+### Supported Ruby versions
 
 This library is supported on Ruby 2.4+.
 
@@ -16,3 +65,154 @@ in security maintenance, and not end of life. Currently, this means Ruby 2.4
 and later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
+
+## Quickstart
+
+### Running Hello World on your local machine
+
+Create a `Gemfile` listing the Functions Framework as a dependency:
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "functions_framework", "~> 0.1"
+```
+
+Create a file called `app.rb` and include the following code. This defines a
+simple function called "hello".
+
+```ruby
+# app.rb
+require "functions_framework"
+
+FunctionsFramework.http("hello") do |request|
+  "Hello, world!\n"
+end
+```
+
+Install the bundle, and start the framework. This spins up a local web server
+running your "hello" function:
+
+```sh
+bundle install
+# ...installs the functions_framework gem and other dependencies
+bundle exec functions-framework --target hello
+# ...starts the web server in the foreground
+```
+
+In a separate shell, you can send requests to this function using curl:
+
+```sh
+curl localhost:8080
+# Output: Hello, world!
+```
+
+Stop the web server with `CTRL+C`.
+
+### Deploying a function to Google Cloud Functions
+
+(Google Cloud Functions does not yet support the Ruby Function Framework)
+
+### Deploying a function to Cloud Run
+
+Create a `Dockerfile` for your function:
+
+```dockerfile
+# Dockerfile
+FROM ruby:2.6
+
+WORKDIR /app
+COPY . .
+RUN gem install --no-document bundler \
+    && bundle config --local frozen true \
+    && bundle install
+
+ENTRYPOINT ["bundle", "exec", "functions-framework"]
+CMD ["--target", "hello"]
+```
+
+Build your function into a Docker image:
+
+```sh
+gcloud builds submit --tag=gcr.io/[YOUR-PROJECT]/hello:build-1
+```
+
+Deploy to Cloud Run:
+
+```sh
+gcloud run deploy hello --image=gcr.io/[YOUR-PROJECT]/hello:build-1 \
+  --platform=managed --allow-unauthenticated --region=us-central1
+```
+
+You can use a similar approach to deploy to any other Knative-based serverless
+environment.
+
+### Responding to CloudEvents
+
+You can also define a function that response to
+[CloudEvents](https://cloudevents.io). The Functions Framework will handle
+unmarshalling of the event data.
+
+Change `app.rb` to read:
+
+```ruby
+# app.rb
+require "functions_framework"
+
+FunctionsFramework.event("my-handler") do |data, context|
+  FunctionsFramework.logger.info "I received #{data.inspect}"
+end
+```
+
+Start up the framework with this new function:
+
+```sh
+bundle install
+bundle exec functions-framework --target my-handler
+```
+
+In a separate shell, you can send a CloudEvent to this function using curl:
+
+```sh
+curl --header "Content-Type: text/plain; charset=utf-8" \
+     --header "CE-ID: 12345" \
+     --header "CE-Source: curl" \
+     --header "CE-Type: com.example.test" \
+     --header "CE-Specversion: 1.0" \
+     --data "Hello, world!" \
+     http://localhost:8080
+```
+
+CloudEvents functions do not return meaningful results, but you will see the
+log message from the web server.
+
+### Configuring the Functions Framework
+
+The Ruby Functions Framework recognizes the standard command line arguments to
+the `functions-framework` executable. Each argument also corresponds to an
+environment variable. If you specify both, the environment variable will be
+ignored.
+
+Command-line flag | Environment variable | Description
+----------------- | -------------------- | -----------
+`--port`          | `PORT`               | The port on which the Functions Framework listens for requests. Default: `8080`
+`--target`        | `FUNCTION_TARGET`    | The name of the exported function to be invoked in response to requests. Default: `function`
+`--source`        | `FUNCTION_SOURCE`    | The path to the file containing your function. Default: `app.rb` (in the current working directory)
+
+Note: the flag `--signature-type` and corresponding environment variable
+`FUNCTION_SIGNATURE_TYPE` are not used by the Ruby Function Framework, because
+you specify the signature type when defining the function in the source.
+
+The Ruby `functions-framework` executable also recognizes several additional
+flags that can be used to control logging verbosity, binding, and other
+parameters. For details, see the online help:
+
+```sh
+functions-framework --help
+```
+
+## For more information
+
+ *  See the `examples` directory for additional examples
+ *  Consult https://rubydoc.info/gems/functions_framework for full reference
+    documentation.

data/bin/functions-framework

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+# 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/cli"
+
+::FunctionsFramework::CLI.new.parse_args(::ARGV).run

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/binary_content.rb

@@ -0,0 +1,59 @@
+# 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.
+
+module FunctionsFramework
+  module CloudEvents
+    ##
+    # A content handler for the binary mode.
+    # See https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md
+    #
+    module BinaryContent
+      class << self
+        ##
+        # Decode an event from the given Rack environment
+        #
+        # @param env [Hash] Rack environment hash
+        # @param content_type [FunctionsFramework::CloudEvents::ContentType]
+        #     the content type from the Rack environment
+        # @return [FunctionsFramework::CloudEvents::Event]
+        #
+        def decode_rack_env env, content_type
+          data = env["rack.input"]&.read
+          spec_version = interpret_header env, "HTTP_CE_SPECVERSION"
+          raise "Unrecognized specversion: #{spec_version}" unless spec_version == "1.0"
+          Event.new \
+            id:                interpret_header(env, "HTTP_CE_ID"),
+            source:            interpret_header(env, "HTTP_CE_SOURCE"),
+            type:              interpret_header(env, "HTTP_CE_TYPE"),
+            spec_version:      spec_version,
+            data:              data,
+            data_content_type: content_type,
+            data_schema:       interpret_header(env, "HTTP_CE_DATASCHEMA"),
+            subject:           interpret_header(env, "HTTP_CE_SUBJECT"),
+            time:              interpret_header(env, "HTTP_CE_TIME")
+        end
+
+        private
+
+        def interpret_header env, key
+          escaped_value = env[key]
+          return nil if escaped_value.nil?
+          escaped_value.gsub(/%([0-9a-fA-F]{2})/) do
+            [$1.to_i(16)].pack "C" # rubocop:disable Style/PerlBackrefs
+          end
+        end
+      end
+    end
+  end
+end

data/lib/functions_framework/cloud_events/content_type.rb

@@ -0,0 +1,139 @@
+# 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.
+
+module FunctionsFramework
+  module CloudEvents
+    ##
+    # A parsed content-type header.
+    #
+    # This object represents the information contained in a Content-Type,
+    # obtained by parsing the header according to RFC 2045.
+    #
+    # Case-insensitive fields, such as media_type and subtype, are normalized
+    # to lower case.
+    #
+    class ContentType
+      ##
+      # Parse the given header value
+      #
+      # @param string [String] Content-Type header value in RFC 2045 format
+      #
+      def initialize string
+        @string = string
+        # TODO: This handles simple cases but is not RFC-822 compliant.
+        sections = string.to_s.split ";"
+        media_type, subtype = sections.shift.split "/"
+        subtype_prefix, subtype_format = subtype.split "+"
+        @media_type = media_type.strip.downcase
+        @subtype = subtype.strip.downcase
+        @subtype_prefix = subtype_prefix.strip.downcase
+        @subtype_format = subtype_format&.strip&.downcase
+        @params = initialize_params sections
+        @canonical_string = "#{@media_type}/#{@subtype}" +
+                            @params.map { |k, v| "; #{k}=#{v}" }.join
+      end
+
+      ##
+      # The original header content string
+      # @return [String]
+      #
+      attr_reader :string
+      alias to_s string
+
+      ##
+      # A "canonical" header content string with spacing and capitalization
+      # normalized.
+      # @return [String]
+      #
+      attr_reader :canonical_string
+
+      ##
+      # The media type.
+      # @return [String]
+      #
+      attr_reader :media_type
+
+      ##
+      # The entire content subtype (which could include an extension delimited
+      # by a plus sign)
+      # @return [String]
+      #
+      attr_reader :subtype
+
+      ##
+      # The portion of the content subtype before any plus sign.
+      # @return [String]
+      #
+      attr_reader :subtype_prefix
+
+      ##
+      # The portion of the content subtype after any plus sign, or nil if there
+      # is no plus sign in the subtype.
+      # @return [String,nil]
+      #
+      attr_reader :subtype_format
+
+      ##
+      # An array of parameters, each element as a two-element array of the
+      # parameter name and value.
+      # @return [Array<Array(String,String)>]
+      #
+      attr_reader :params
+
+      ##
+      # An array of values for the given parameter name
+      # @param key [String]
+      # @return [Array<String>]
+      #
+      def param_values key
+        key = key.downcase
+        @params.inject([]) { |a, (k, v)| key == k ? a << v : a }
+      end
+
+      ##
+      # The first value of the "charset" parameter, or nil if there is no
+      # charset.
+      # @return [String,nil]
+      #
+      def charset
+        param_values("charset").first
+      end
+
+      ## @private
+      def == other
+        other.is_a?(ContentType) && canonical_string == other.canonical_string
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        canonical_string.hash
+      end
+
+      private
+
+      def initialize_params sections
+        params = sections.map do |s|
+          k, v = s.split "="
+          [k.strip.downcase, v.strip]
+        end
+        params.sort! do |(k1, v1), (k2, v2)|
+          a = k1 <=> k2
+          a.zero? ? v1 <=> v2 : a
+        end
+        params
+      end
+    end
+  end
+end