faastruby-rpc 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6156f5bfcd486038697b1ba4e232093527fe1794c7616ab12405047a1e2659fd
-  data.tar.gz: 8cc0fd2b4c0c954bf71034335a77696ec96d337e8cae58ad587722772d5f1be8
+  metadata.gz: e0399784305d0de9f8ee8db0f602cc2062a1c1d8d631bdfd0514c1d5b846e7c0
+  data.tar.gz: f437fe5dce46945b840117d3cfa6a0b68699046b7f0a64ba7822fd2278dcc4cc
 SHA512:
-  metadata.gz: 4af94ef769bfe71c805c5896ce1d07bba252f335ccad7c856189fcfc9c40d1dcd6175db6db08e200cb92c0d16bedf216b143cd64ea706703599793c7ba6bfbb0
-  data.tar.gz: 06cd23c88f89e7394b9374dfadf5d597c38f45435f7500dd66864e6fd7a56396dd18754cfe2818af7746de3f61deb2629fdd64d81a6982217b9e921ef983d29b
+  metadata.gz: ab2e9df498673377e78ba3d94103a4cc07daca5ce7bcd601aede51ded5e60a74560821e5cc51089a988fbfd45a448c14a88dcb5825ea79d5a2facf1ad2d70643
+  data.tar.gz: a946ba11384ce3d9ec7a090f9be8405b9a69e69400fe153cff602a2cc2fd35e815c7474296f9dde19c8128f4c7e5db68396cf62e490d974aaf00dedc4fe8b222

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 0.2.0 - Dec 31 2018
+- Redesigned UX for calling of external functions
+
 ## 0.1.3 - Dec 15 2018
 - Add test helper to stub invoke()
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    faastruby-rpc (0.1.3)
+    faastruby-rpc (0.1.4)
       oj (~> 3.6)
 
 GEM
@@ -13,7 +13,7 @@ GEM
       safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
     hashdiff (0.3.7)
-    oj (3.7.4)
+    oj (3.7.6)
     public_suffix (3.0.3)
     rake (10.5.0)
     rspec (3.8.0)
@@ -46,4 +46,4 @@ DEPENDENCIES
   webmock (~> 3.4)
 
 BUNDLED WITH
-   1.16.5
+   1.17.3

data/README.md

@@ -5,69 +5,76 @@ Wrapper to make it easy to call FaaStRuby functions.
 #### What is FaaStRuby?
 FaaStRuby is a serverless platform built for Ruby developers.
 
-* [Tutorial](https://faastruby.io/tutorial.html)
+* [Tutorial](https://faastruby.io/getting-started)
 
-## Calling functions from within a function
+## Calling functions from within a function (RPC calls)
 
-To call a function, use the helper method `invoke`:
+To call another function you must first require it on the top of `handler.rb`, passing a string that will be converted to a constant. You then use the constant to call the function and get its response.
+
+To call the function, use the method `call`. Here is an example.
 
 ```ruby
-# You need the function path, which is WORKSPACE_NAME/FUNCTION_NAME
-function = 'paulo/hello'
-# Invoke the function the get the result
-result = invoke(function).call
-# Or passing arguments:
-result = invoke(function).with('Paulo', likes_ruby: true)
+require_function 'paulo/hello-world', as: 'HelloWorld'
+def handler(event)
+  hello = HelloWorld.call # Async call
+  hello.class #=> FaaStRuby::RPC::Function
+  hello.returned? #=> false # READ BELOW TO UNDERSTAND
+  hello #=> 'Hello, World!' - The RPC response body
+  hello.body #=> 'Hello, World!' - Also the RPC response body
+  hello.returned? #=> true # READ BELOW TO UNDERSTAND
+  hello.code #=> 200 - The status code
+  hello.headers #=> {"content-type"=>"text/plain", "x-content-type-options"=>"nosniff", "connection"=>"close", "content-length"=>"5"} - The response headers
+  render text: hello
+end
 ```
+The biggest problem with serverless applications is the latency resultant of multiple calls to different functions. This is called Tail Latency.
+To minimize this problem, `faastruby-rpc` will handle the request to other functions in an async fashion.
+You should design your application with that in mind. For example, you can design your application so the external function calls are done early in the program execution and perform other tasks while you wait for the response.
 
-`result` is a Struct with the following attributes:
-* result.body - The response body from the function you called
-* result.code - The HTTP status code returned by the function
-* result.headers - The headers returned by the functions
+In the example above, `hello = HelloWorld.call` will issue a non-blocking HTTP request in a separate thread to the called function's endpoint, assign it to a variable and continue execution. When you need the return value from that function, just use the variable. If you call the variable before the request is completed, the execution will block until an answer is received from the external function. To minimize tail latency, just design your application around those async calls.
 
-The arguments in `with` are passed as arguments to your function (after the `event`). You can capture them with positional arguments, keyword arguments or just a generic `*args` if you want to have the flexibility of sending a variable number of arguments.
+If at any point you need to know if the external function call already returned without blocking the execution of your program, use the method `returned?`. So in the example above, `hello.returned?` will be false until the request is fulfilled.
 
-Here is the source code of `paulo/hello`:
+## Passing arguments to the called function
+
+Say you have the following function in `my-workspace/echo`:
 
 ```ruby
-def handler event, name = nil
-  response = name ? "Hello, #{name}!" : 'Hello, there!'
-  render text: response
+# Note the required keyword argument 'name:'
+def handler(event, name:)
+  render text: name
 end
 ```
 
-When you call `invoke`, a request is sent with the following properties:
-* method: POST
-* header `Content-Type: application/json`
-* header `Faastruby-Rpc: true`
-* body: JSON array
+If you want to call this function in another function, you can simply pass the argument within `call`:
 
-`invoke` is just a helper to the following method:
 ```ruby
-# Calling a function that way defaults to method=GET
-FaaStRuby::RPC::Function.new("FUNCTION_PATH").call(body: nil, query_params: {}, headers: {}, method: 'get')
+require_function 'my-workspace/echo', as: 'Echo'
+def handler(event)
+  name = Echo.call(name: 'John Doe') # Async call
+  render text: "Hello, #{name}!" # calling 'name' will block until Echo returns
+end
 ```
+You can use positional or keyword arguments when calling external functions, as long as the external function's `handler` method is defined with matching arguments.
 
 This gem is already required when you run your functions in FaaStRuby, or using `faastruby server`.
 
 ## Handling errors
 
-By default, an exception is raised if the invoked function HTTP status code is greater than 400. This is important to make your functions easier to debug, and you will always know what to expect from that function call.
+By default, an exception is raised if the invoked function HTTP status code is greater or equal to 400. This is important to make your functions easier to debug, and you will always know what to expect from that function call.
 
-To disable this behaviour, pass `raise_errors: false` to the `invoke` method, or to `FaaStRuby::RPC::Function.new`. Example:
+To disable this behaviour, pass `raise_errors: false` when requiring the function. For example:
 
 ```ruby
-invoke('paulo/hello', raise_errors: false).call
-# or
-FaaStRuby::RPC::Function.new("paulo/hello", raise_errors: false).call(body: nil)
+require_function 'paulo/hello-world', as: 'HelloWorld', raise_errors: false
 ```
 
-## Stubbing invoke() in your function tests
-If you are testing a function that invokes another one, you likely will want to fake that call. To do that, use the following test helper:
+## Stubbing RPC calls in your function tests
+If you are testing a function that required another one, you likely will want to fake that call. To do that, use the following test helper:
 
 ```ruby
-# This will cause invoke('paulo/hello-world')... to fake the call to
-# 'paulo/hello-world' and instead return the values you pass in the block.
+# This will make it fake the calls to 'paulo/hello-world'
+# and return the values you pass in the block.
 require 'faastruby-rpc/test_helper'
 
 FaaStRuby::RPC.stub_call('paulo/hello-world') do |response|

data/lib/faastruby-rpc/function.rb

@@ -1,25 +1,20 @@
 module FaaStRuby
   FAASTRUBY_HOST = ENV['FAASTRUBY_HOST'] || "http://localhost:3000"
   module RPC
-    @@response = {}
-    def self.stub_call(function_path, &block)
-      helper = TestHelper.new
-      block.call(helper)
-      response = Struct.new(:body, :code, :headers, :klass)
-      @@response[function_path] = response.new(helper.body, helper.code, helper.headers, helper.klass)
-    end
-    def self.stub_call?(path)
-      @@response[path]
-    end
-
-    def self.response(path)
-      @@response[path]
-    end
-
     class ExecutionError < StandardError
     end
+    class Response
+      attr_reader :body, :code, :headers, :klass
+      def initialize(body, code, headers, klass = nil)
+        @body = body
+        @code = code
+        @headers = headers
+        @klass = klass
+      end
+    end
     class Function
       def initialize(path, raise_errors: true)
+        @response = nil
         @path = path
         @methods = {
           'post' => Net::HTTP::Post,
@@ -28,51 +23,96 @@ module FaaStRuby
           'patch' => Net::HTTP::Patch,
           'delete' => Net::HTTP::Delete
         }
-        @response = Struct.new(:body, :code, :headers, :klass)
         @raise_errors = raise_errors
       end
-      def with(*args)
-        call(body: Oj.dump(args), headers: {'Content-Type' => 'application/json', 'Faastruby-Rpc' => 'true'})
+      def call_with(*args)
+        execute(req_body: Oj.dump(args), headers: {'Content-Type' => 'application/json', 'Faastruby-Rpc' => 'true'})
       end
 
-      def call(body: nil, query_params: {}, headers: {}, method: 'post')
-        url = "#{FAASTRUBY_HOST}/#{@path}#{convert_query_params(query_params)}"
-        uri = URI.parse(url)
-        use_ssl = uri.scheme == 'https' ? true : false
-        response = FaaStRuby::RPC.stub_call?(@path) ? FaaStRuby::RPC.response(@path) : fetch(use_ssl: use_ssl, uri: uri, headers: headers, method: @methods[method], body: body)
-        resp_headers = {}
-        response.each{|k,v| resp_headers[k] = v}
-        case resp_headers['content-type']
-        when 'application/json'
-          begin
-            resp_body = Oj.load(response.body)
-          rescue Oj::ParseError => e
-            if response.body.is_a?(String)
-              resp_body = response.body
-            else
-              raise e if @raise_errors
-              resp_body = {
-                'error' => e.message,
-                'location' => e.backtrace&.first
-              }
+      def call(*args)
+        return call_with(*args) if args.any?
+        execute(method: 'get')
+      end
+
+      def execute(req_body: nil, query_params: {}, headers: {}, method: 'post')
+        @thread = Thread.new do
+          url = "#{FAASTRUBY_HOST}/#{@path}#{convert_query_params(query_params)}"
+          uri = URI.parse(url)
+          use_ssl = uri.scheme == 'https' ? true : false
+          response = fetch(use_ssl: use_ssl, uri: uri, headers: headers, method: @methods[method], req_body: req_body)
+          resp_headers = {}
+          response.each{|k,v| resp_headers[k] = v}
+          case resp_headers['content-type']
+          when 'application/json'
+            begin
+              resp_body = Oj.load(response.body)
+            rescue Oj::ParseError => e
+              if response.body.is_a?(String)
+                resp_body = response.body
+              else
+                raise e if @raise_errors
+                resp_body = {
+                  'error' => e.message,
+                  'location' => e.backtrace&.first
+                }
+              end
             end
+          when 'application/yaml'
+            resp_body = YAML.load(response.body)
+          else
+            resp_body = response.body
           end
-        when 'application/yaml'
-          resp_body = YAML.load(response.body)
-        else
-          resp_body = response.body
+          raise FaaStRuby::RPC::ExecutionError.new("Function #{@path} returned status code #{response.code} - #{resp_body['error']} - #{resp_body['location']}") if response.code.to_i >= 400 && @raise_errors
+          @response = FaaStRuby::RPC::Response.new(resp_body, response.code.to_i, resp_headers)
         end
-        raise FaaStRuby::RPC::ExecutionError.new("Function #{@path} returned status code #{response.code} - #{resp_body['error']} - #{resp_body['location']}") if response.code.to_i >= 400 && @raise_errors
-        @response.new(resp_body, response.code.to_i, resp_headers)
+        self
+      end
+
+      def returned?
+        !@response.nil?
+      end
+
+      def response
+        wait unless returned?
+        @response
+      end
+
+      def to_s
+        body || ""
+      end
+
+      def body
+        # wait unless returned?
+        response.body
+      end
+
+      def code
+        # wait unless returned?
+        response.code
+      end
+
+      def headers
+        # wait unless returned?
+        response.headers
+      end
+
+      def klass
+        # wait unless returned?
+        response.klass
       end
 
       private
+
+      def wait
+        @thread.join
+      end
+
       def convert_query_params(query_params)
         return "" unless query_params.any?
         "?#{URI.encode_www_form(query_params)}"
       end
 
-      def fetch(use_ssl:, uri:, limit: 10, method: Net::HTTP::Post, headers: {}, body: nil)
+      def fetch(use_ssl:, uri:, limit: 10, method: Net::HTTP::Post, headers: {}, req_body: nil)
         # You should choose a better exception.
         raise ArgumentError, 'too many HTTP redirects' if limit == 0
         http = Net::HTTP.new(uri.host, uri.port)
@@ -81,7 +121,7 @@ module FaaStRuby
           http.ssl_options = OpenSSL::SSL::OP_NO_SSLv2 + OpenSSL::SSL::OP_NO_SSLv3 + OpenSSL::SSL::OP_NO_COMPRESSION
         end
         request = method.new(uri.request_uri, headers)
-        request.body = body
+        request.body = req_body
         response = http.request(request)
 
         case response

data/lib/faastruby-rpc/test_helper.rb

@@ -1,6 +1,19 @@
 require 'faastruby-rpc'
 module FaaStRuby
   module RPC
+    @@response = {}
+    def self.stub_call(function_path, &block)
+      helper = TestHelper.new
+      block.call(helper)
+      @@response[function_path] = FaaStRuby::RPC::Response.new(helper.body, helper.code, helper.headers, helper.klass)
+    end
+    def self.stub_call?(path)
+      @@response[path]
+    end
+
+    def self.response(path)
+      @@response[path]
+    end
     class TestHelper
       attr_accessor :body, :code, :headers, :klass
       def initialize
@@ -12,3 +25,39 @@ module FaaStRuby
     end
   end
 end
+
+FaaStRuby::RPC::Function.class_eval do
+  def execute(req_body: nil, query_params: {}, headers: {}, method: 'post')
+    @thread = Thread.new do
+      url = "#{FAASTRUBY_HOST}/#{@path}#{convert_query_params(query_params)}"
+      uri = URI.parse(url)
+      use_ssl = uri.scheme == 'https' ? true : false
+      response = FaaStRuby::RPC.response(@path)
+      resp_headers = {}
+      response.headers.each{|k,v| resp_headers[k] = v}
+      case resp_headers['content-type']
+      when 'application/json'
+        begin
+          resp_body = Oj.load(response.body)
+        rescue Oj::ParseError => e
+          if response.body.is_a?(String)
+            resp_body = response.body
+          else
+            raise e if @raise_errors
+            resp_body = {
+              'error' => e.message,
+              'location' => e.backtrace&.first
+            }
+          end
+        end
+      when 'application/yaml'
+        resp_body = YAML.load(response.body)
+      else
+        resp_body = response.body
+      end
+      raise FaaStRuby::RPC::ExecutionError.new("Function #{@path} returned status code #{response.code} - #{resp_body['error']} - #{resp_body['location']}") if response.code.to_i >= 400 && @raise_errors
+      @response = FaaStRuby::RPC::Response.new(resp_body, response.code.to_i, resp_headers)
+    end
+    self
+  end
+end

data/lib/faastruby-rpc/version.rb

@@ -1,5 +1,5 @@
 module FaaStRuby
   module RPC
-    VERSION = '0.1.3'
+    VERSION = '0.2.0'
   end
 end

data/lib/faastruby-rpc.rb

@@ -13,5 +13,15 @@ Net::HTTP.class_eval do
 end
 
 def invoke(function, raise_errors: true)
+  function(function, raise_errors: raise_errors)
+end
+
+def function(function, raise_errors: true)
   FaaStRuby::RPC::Function.new(function, raise_errors: raise_errors)
 end
+
+def require_function(function, as:, raise_errors: true)
+  Object.send(:remove_const, as.capitalize) if Object.const_defined?(as.capitalize)
+  Object.const_set as.capitalize, FaaStRuby::RPC::Function.new(function, raise_errors: raise_errors)
+  return false
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faastruby-rpc
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Paulo Arruda
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-15 00:00:00.000000000 Z
+date: 2018-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj