functions_framework 0.1.1 → 0.2.0

data/lib/functions_framework/cloud_events/json_format.rb

@@ -0,0 +1,122 @@
+# 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 "base64"
+require "json"
+
+module FunctionsFramework
+  module CloudEvents
+    ##
+    # An implementation of JSON format and JSON batch format.
+    #
+    # See https://github.com/cloudevents/spec/blob/master/json-format.md
+    #
+    class JsonFormat
+      ##
+      # Decode an event from the given input JSON string.
+      #
+      # @param json [String] A JSON-formatted string
+      # @return [FunctionsFramework::CloudEvents::Event]
+      #
+      def decode json, **_other_kwargs
+        structure = ::JSON.parse json
+        decode_hash_structure structure
+      end
+
+      ##
+      # Encode an event to a JSON string.
+      #
+      # @param event [FunctionsFramework::CloudEvents::Event] An input event.
+      # @param sort [boolean] Whether to sort keys of the JSON output.
+      # @return [String] The JSON representation.
+      #
+      def encode event, sort: false, **_other_kwargs
+        structure = encode_hash_structure event
+        structure = sort_keys structure if sort
+        ::JSON.dump structure
+      end
+
+      ##
+      # Decode a batch of events from the given input string.
+      #
+      # @param json [String] A JSON-formatted string
+      # @return [Array<FunctionsFramework::CloudEvents::Event>]
+      #
+      def decode_batch json, **_other_kwargs
+        structure_array = Array(::JSON.parse(json))
+        structure_array.map do |structure|
+          decode_hash_structure structure
+        end
+      end
+
+      ##
+      # Encode a batch of event to a JSON string.
+      #
+      # @param events [Array<FunctionsFramework::CloudEvents::Event>] An array
+      #     of input events.
+      # @param sort [boolean] Whether to sort keys of the JSON output.
+      # @return [String] The JSON representation.
+      #
+      def encode_batch events, sort: false, **_other_kwargs
+        structure_array = Array(events).map do |event|
+          structure = encode_hash_structure event
+          sort ? sort_keys(structure) : structure
+        end
+        ::JSON.dump structure_array
+      end
+
+      ##
+      # Decode a single event from a hash data structure with keys and types
+      # conforming to the JSON event format.
+      #
+      # @param structure [Hash] An input hash.
+      # @return [FunctionsFramework::CloudEvents::Event]
+      #
+      def decode_hash_structure structure
+        if structure.key? "data_base64"
+          structure = structure.dup
+          structure["data"] = ::Base64.decode64 structure.delete "data_base64"
+        end
+        Event.create spec_version: structure["specversion"], attributes: structure
+      end
+
+      ##
+      # Encode a single event to a hash data structure with keys and types
+      # conforming to the JSON event format.
+      #
+      # @param event [FunctionsFramework::CloudEvents::Event] An input event.
+      # @return [String] The hash structure.
+      #
+      def encode_hash_structure event
+        structure = event.to_h
+        data = structure["data"]
+        if data.is_a?(::String) && data.encoding == ::Encoding::ASCII_8BIT
+          structure.delete "data"
+          structure["data_base64"] = ::Base64.encode64 data
+        end
+        structure
+      end
+
+      private
+
+      def sort_keys hash
+        result = {}
+        hash.keys.sort.each do |key|
+          result[key] = hash[key]
+        end
+        result
+      end
+    end
+  end
+end

data/lib/functions_framework/function.rb

@@ -54,11 +54,9 @@ module FunctionsFramework
     #
     #  *  A `:http` type function takes a `Rack::Request` argument, and returns
     #     a Rack response type. See {FunctionsFramework::Registry.add_http}.
-    #  *  A `:event` or `:cloud_event` type function takes a
+    #  *  A `:cloud_event` type function takes a
     #     {FunctionsFramework::CloudEvents::Event} argument, and does not
     #     return a value. See {FunctionsFramework::Registry.add_cloud_event}.
-    #     Note that for an `:event` type function, the passed event argument is
-    #     split into two arguments when passed to the underlying block.
     #
     # @param argument [Rack::Request,FunctionsFramework::CloudEvents::Event]
     # @return [Object]

data/lib/functions_framework/legacy_event_converter.rb

@@ -0,0 +1,136 @@
+# 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"
+
+module FunctionsFramework
+  ##
+  # Converter from legacy GCF event formats to CloudEvents.
+  #
+  class LegacyEventConverter
+    ##
+    # Decode an event from the given Rack environment hash.
+    #
+    # @param env [Hash] The Rack environment
+    # @return [FunctionsFramework::CloudEvents::Event] if the request could
+    #     be converted
+    # @return [nil] if the event format was not recognized.
+    #
+    def decode_rack_env env
+      content_type = CloudEvents::ContentType.new env["CONTENT_TYPE"]
+      return nil unless content_type.media_type == "application" && content_type.subtype_prefix == "json"
+      input = read_input_json env["rack.input"], content_type.charset
+      return nil unless input
+      raw_context = input["context"] || input
+      context = normalized_context raw_context
+      return nil unless context
+      construct_cloud_event context, input["data"]
+    end
+
+    private
+
+    def read_input_json input, charset
+      input = input.read if input.respond_to? :read
+      input = input.encode charset if charset
+      content = ::JSON.parse input
+      content = nil unless content.is_a? ::Hash
+      content
+    rescue ::JSON::ParserError
+      nil
+    end
+
+    def normalized_context raw_context
+      id = raw_context["eventId"]
+      return nil unless id
+      timestamp = raw_context["timestamp"]
+      return nil unless timestamp
+      type = raw_context["eventType"]
+      return nil unless type
+      service, resource = analyze_resource raw_context["resource"], type
+      return nil unless service && resource
+      { id: id, timestamp: timestamp, type: type, service: service, resource: resource }
+    end
+
+    def analyze_resource raw_resource, type
+      case raw_resource
+      when ::Hash
+        [raw_resource["service"], raw_resource["name"]]
+      when ::String
+        [service_from_type(type), raw_resource]
+      else
+        [nil, nil]
+      end
+    end
+
+    def service_from_type type
+      LEGACY_TYPE_TO_SERVICE.each do |pattern, service|
+        return service if pattern =~ type
+      end
+      nil
+    end
+
+    def construct_cloud_event context, data
+      source, subject = convert_source context[:service], context[:resource]
+      type = LEGACY_TYPE_TO_CE_TYPE[context[:type]]
+      return nil unless type && source
+      CloudEvents::Event.new id:                context[:id],
+                             source:            source,
+                             type:              type,
+                             spec_version:      "1.0",
+                             data_content_type: "application/json",
+                             data:              data,
+                             subject:           subject,
+                             time:              context[:timestamp]
+    end
+
+    def convert_source service, resource
+      if service == "storage.googleapis.com"
+        match = %r{^(projects/[^/]+/buckets/[^/]+)/([^#]+)(?:#.*)?$}.match resource
+        return [nil, nil] unless match
+        ["//#{service}/#{match[1]}", match[2]]
+      else
+        ["//#{service}/#{resource}", nil]
+      end
+    end
+
+    LEGACY_TYPE_TO_SERVICE = {
+      %r{^providers/cloud\.firestore/} => "firestore.googleapis.com",
+      %r{^providers/cloud\.pubsub/}    => "pubsub.googleapis.com",
+      %r{^providers/cloud\.storage/}   => "storage.googleapis.com",
+      %r{^providers/firebase\.auth/}   => "firebase.googleapis.com",
+      %r{^providers/google\.firebase}  => "firebase.googleapis.com"
+    }.freeze
+
+    LEGACY_TYPE_TO_CE_TYPE = {
+      "google.pubsub.topic.publish"                              => "google.cloud.pubsub.topic.v1.messagePublished",
+      "providers/cloud.pubsub/eventTypes/topic.publish"          => "google.cloud.pubsub.topic.v1.messagePublished",
+      "google.storage.object.finalize"                           => "google.cloud.storage.object.v1.finalized",
+      "google.storage.object.delete"                             => "google.cloud.storage.object.v1.deleted",
+      "google.storage.object.archive"                            => "google.cloud.storage.object.v1.archived",
+      "google.storage.object.metadataUpdate"                     => "google.cloud.storage.object.v1.metadataUpdated",
+      "providers/cloud.firestore/eventTypes/document.write"      => "google.cloud.firestore.document.v1.written",
+      "providers/cloud.firestore/eventTypes/document.create"     => "google.cloud.firestore.document.v1.created",
+      "providers/cloud.firestore/eventTypes/document.update"     => "google.cloud.firestore.document.v1.updated",
+      "providers/cloud.firestore/eventTypes/document.delete"     => "google.cloud.firestore.document.v1.deleted",
+      "providers/firebase.auth/eventTypes/user.create"           => "google.firebase.auth.user.v1.created",
+      "providers/firebase.auth/eventTypes/user.delete"           => "google.firebase.auth.user.v1.deleted",
+      "providers/google.firebase.analytics/eventTypes/event.log" => "google.firebase.analytics.log.v1.written",
+      "providers/google.firebase.database/eventTypes/ref.create" => "google.firebase.database.document.v1.created",
+      "providers/google.firebase.database/eventTypes/ref.write"  => "google.firebase.database.document.v1.written",
+      "providers/google.firebase.database/eventTypes/ref.update" => "google.firebase.database.document.v1.updated",
+      "providers/google.firebase.database/eventTypes/ref.delete" => "google.firebase.database.document.v1.deleted",
+      "providers/cloud.storage/eventTypes/object.change"         => "google.cloud.storage.object.v1.finalized"
+    }.freeze
+  end
+end

data/lib/functions_framework/registry.rb

@@ -76,31 +76,10 @@ module FunctionsFramework
     end
 
     ##
-    # Add a CloudEvent function to the registry.
-    #
-    # 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`.
+    # This is an obsolete interface that defines an event function taking two
+    # arguments (data and context) rather than one.
     #
-    # See also {#add_cloud_event} which creates a function that takes a single
-    # argument of type {FunctionsFramework::CloudEvents::Event}.
-    #
-    # @param name [String] The function name
-    # @param block [Proc] The function code as a proc
-    # @return [self]
+    # @deprecated Use {Registry#add_cloud_event} instead.
     #
     def add_event name, &block
       name = name.to_s
@@ -118,9 +97,6 @@ module FunctionsFramework
     # function. The block should take _one_ argument: the event object of type
     # {FunctionsFramework::CloudEvents::Event}. Any return value is ignored.
     #
-    # See also {#add_event} which creates a function that takes data and
-    # context as separate arguments.
-    #
     # @param name [String] The function name
     # @param block [Proc] The function code as a proc
     # @return [self]

data/lib/functions_framework/server.rb

@@ -212,7 +212,7 @@ module FunctionsFramework
       # @param bind_addr [String,nil]
       #
       def bind_addr= bind_addr
-        @bind_addr = bind_addr || ::ENV["BIND_ADDR"] || "0.0.0.0"
+        @bind_addr = bind_addr || ::ENV["FUNCTION_BIND_ADDR"] || "0.0.0.0"
       end
 
       ##
@@ -228,7 +228,7 @@ module FunctionsFramework
       # @param min_threads [Integer,nil]
       #
       def min_threads= min_threads
-        @min_threads = (min_threads || ::ENV["MIN_THREADS"])&.to_i
+        @min_threads = (min_threads || ::ENV["FUNCTION_MIN_THREADS"])&.to_i
       end
 
       ##
@@ -236,7 +236,7 @@ module FunctionsFramework
       # @param max_threads [Integer,nil]
       #
       def max_threads= max_threads
-        @max_threads = (max_threads || ::ENV["MAX_THREADS"])&.to_i
+        @max_threads = (max_threads || ::ENV["FUNCTION_MAX_THREADS"])&.to_i
       end
 
       ##
@@ -244,8 +244,12 @@ module FunctionsFramework
       # @param show_error_details [Boolean,nil]
       #
       def show_error_details= show_error_details
-        val = show_error_details.nil? ? ::ENV["DETAILED_ERRORS"] : show_error_details
-        @show_error_details = val ? true : false
+        @show_error_details =
+          if show_error_details.nil?
+            !::ENV["FUNCTION_DETAILED_ERRORS"].to_s.empty?
+          else
+            show_error_details ? true : false
+          end
       end
 
       ##
@@ -315,15 +319,15 @@ module FunctionsFramework
 
     ## @private
     class AppBase
-      BLACKLISTED_PATHS = ["/favicon.ico", "/robots.txt"].freeze
+      EXCLUDED_PATHS = ["/favicon.ico", "/robots.txt"].freeze
 
       def initialize config
         @config = config
       end
 
-      def blacklisted_path? env
+      def excluded_path? env
         path = env[::Rack::SCRIPT_NAME].to_s + env[::Rack::PATH_INFO].to_s
-        BLACKLISTED_PATHS.include? path
+        EXCLUDED_PATHS.include? path
       end
 
       def interpret_response response
@@ -335,15 +339,13 @@ module FunctionsFramework
         when ::String
           string_response response, "text/plain", 200
         when ::Hash
-          json = ::JSON.dump response
-          string_response json, "application/json", 200
+          string_response ::JSON.dump(response), "application/json", 200
+        when CloudEvents::CloudEventsError
+          cloud_events_error_response response
         when ::StandardError
-          error = error_message response
-          string_response error, "text/plain", 500
+          error_response "#{response.class}: #{response.message}\n#{response.backtrace}\n"
         else
-          e = ::StandardError.new "Unexpected response type: #{response.class}"
-          error = error_message e
-          string_response error, "text/plain", 500
+          error_response "Unexpected response type: #{response.class}"
         end
       end
 
@@ -359,20 +361,15 @@ module FunctionsFramework
         [status, headers, [string]]
       end
 
-      def error_message error
-        if @config.show_error_details?
-          "#{error.class}: #{error.message}\n#{error.backtrace}\n"
-        else
-          "Unexpected internal error"
-        end
+      def cloud_events_error_response error
+        @config.logger.warn error
+        string_response "#{error.class}: #{error.message}", "text/plain", 400
       end
 
-      def usage_message error
-        if @config.show_error_details?
-          "Failed to decode CloudEvent: #{error.inspect}"
-        else
-          "Failed to decode CloudEvent"
-        end
+      def error_response message
+        @config.logger.error message
+        message = "Unexpected internal error" unless @config.show_error_details?
+        string_response message, "text/plain", 500
       end
     end
 
@@ -384,7 +381,7 @@ module FunctionsFramework
       end
 
       def call env
-        return notfound_response if blacklisted_path? env
+        return notfound_response if excluded_path? env
         response =
           begin
             logger = env["rack.logger"] = @config.logger
@@ -392,7 +389,6 @@ module FunctionsFramework
             logger.info "FunctionsFramework: Handling HTTP #{request.request_method} request"
             @function.call request
           rescue ::StandardError => e
-            logger.warn e
             e
           end
         interpret_response response
@@ -404,33 +400,45 @@ module FunctionsFramework
       def initialize function, config
         super config
         @function = function
+        @cloud_events = CloudEvents::HttpBinding.default
+        @legacy_events = LegacyEventConverter.new
       end
 
       def call env
-        return notfound_response if blacklisted_path? env
+        return notfound_response if excluded_path? env
         logger = env["rack.logger"] = @config.logger
-        event =
-          begin
-            CloudEvents.decode_rack_env env
-          rescue ::StandardError => e
-            e
-          end
+        event = decode_event env
         response =
-          if event.is_a? CloudEvents::Event
-            logger.info "FunctionsFramework: Handling CloudEvent"
-            begin
-              @function.call event
-              "ok"
-            rescue ::StandardError => e
-              logger.warn e
-              e
-            end
+          case event
+          when CloudEvents::Event
+            handle_cloud_event event, logger
+          when ::Array
+            CloudEvents::HttpContentError.new "Batched CloudEvents are not supported"
+          when CloudEvents::CloudEventsError
+            event
           else
-            logger.warn e.inspect
-            string_response usage_message(e), "text/plain", 400
+            raise "Unexpected event type: #{event.class}"
           end
         interpret_response response
       end
+
+      private
+
+      def decode_event env
+        @cloud_events.decode_rack_env(env) ||
+          @legacy_events.decode_rack_env(env) ||
+          raise(CloudEvents::HttpContentError, "Unrecognized event format")
+      rescue CloudEvents::CloudEventsError => e
+        e
+      end
+
+      def handle_cloud_event event, logger
+        logger.info "FunctionsFramework: Handling CloudEvent"
+        @function.call event
+        "ok"
+      rescue ::StandardError => e
+        e
+      end
     end
   end
 end