twirp 0.1.0 → 0.2.0

data/lib/twirp/error.rb

@@ -26,15 +26,15 @@ module Twirp
   # List of all valid error codes in Twirp
   ERROR_CODES = ERROR_CODES_TO_HTTP_STATUS.keys
 
-  def valid_error_code?(code)
-    ERROR_CODES_TO_HTTP_STATUS.key? code # one of the valid symbols
-  end
-
 
   # Twirp::Error represents an error response from a Twirp service.
   # Twirp::Error is not an Exception to be raised, but a value to be returned
   # by service handlers and received by clients.
-	class Error
+  class Error
+
+    def self.valid_code?(code)
+      ERROR_CODES_TO_HTTP_STATUS.key? code # one of the valid symbols
+    end
 
     # Use this constructors to ensure the errors have valid error codes. Example:
     #     Twirp::Error.internal("boom")
@@ -54,7 +54,7 @@ module Twirp
     end
 
     attr_reader :code, :msg, :meta
-    
+
     attr_accessor :cause # used when wrapping another error, but this is not serialized
 
     # Initialize a Twirp::Error
@@ -77,7 +77,11 @@ module Twirp
     end
 
     def to_s
-      "<Twirp::Error code:#{code.inspect} msg:#{msg.inspect} meta:#{meta.inspect}>"
+      "<Twirp::Error code:#{code} msg:#{msg.inspect} meta:#{meta.inspect}>"
+    end
+
+    def inspect
+      to_s
     end
 
 
@@ -89,7 +93,7 @@ module Twirp
       if !meta.is_a? Hash
         raise ArgumentError.new("Twirp::Error meta must be a Hash, but it is a #{meta.class.to_s}")
       end
-      meta.each do |key, value| 
+      meta.each do |key, value|
         if !value.is_a?(String)
           raise ArgumentError.new("Twirp::Error meta values must be Strings, but key #{key.inspect} has the value <#{value.class.to_s}> #{value.inspect}")
         end

data/lib/twirp/service.rb

@@ -1,68 +1,21 @@
 require "json"
 
+require_relative "error"
+require_relative "service_dsl"
+
 module Twirp
 
   class Service
 
-    class << self
-
-      # Configure service package name.
-      def package(name)
-        @package_name = name.to_s
-      end
-
-      # Configure service name.
-      def service(name)
-        @service_name = name.to_s
-      end
-
-      # Configure service routing to handle rpc calls.
-      def rpc(rpc_method, input_class, output_class, opts)
-        raise ArgumentError.new("input_class must be a Protobuf Message class") unless input_class.is_a?(Class) 
-        raise ArgumentError.new("output_class must be a Protobuf Message class") unless output_class.is_a?(Class)
-        raise ArgumentError.new("opts[:handler_method] is mandatory") unless opts && opts[:handler_method]
-
-        @base_envs ||= {}
-        @base_envs[rpc_method.to_s] = {
-          rpc_method: rpc_method.to_sym,
-          input_class: input_class,
-          output_class: output_class,
-          handler_method: opts[:handler_method].to_sym,
-        }
-      end
-
-      # Get configured package name as String.
-      # And empty value means that there's no package.
-      def package_name
-        @package_name.to_s
-      end
-
-      # Service name as String.
-      # Defaults to the current class name.
-      def service_name
-        (@service_name || self.name).to_s
-      end
-
-      # Base Twirp environments for each rpc method.
-      def base_envs
-        @base_envs || {}
-      end
-
-      # Package and servicce name, as a unique identifier for the service,
-      # for example "example.v3.Haberdasher" (package "example.v3", service "Haberdasher").
-      # This can be used as a path prefix to route requests to the service, because a Twirp URL is:
-      # "#{BaseURL}/#{ServiceFullName}/#{Method]"
-      def service_full_name
-        package_name.empty? ? service_name : "#{package_name}.#{service_name}"
-      end
+    # DSL to define a service with package, service and rpcs.
+    extend ServiceDSL
 
+    class << self
       # Raise exceptions instead of handling them with exception_raised hooks.
       # Useful during tests to easily debug and catch unexpected exceptions.
       # Default false.
       attr_accessor :raise_exceptions
-
-    end # class << self
-
+    end
 
     def initialize(handler)
       @handler = handler
@@ -73,20 +26,16 @@ module Twirp
       @exception_raised = []
     end
 
-    def name
-      self.class.service_name
-    end
-
-    def full_name
-      self.class.service_full_name # use to route requests to this servie
-    end
-
-    # Setup hook blocks
+    # Setup hook blocks.
     def before(&block) @before << block; end
     def on_success(&block) @on_success << block; end
     def on_error(&block) @on_error << block; end
     def exception_raised(&block) @exception_raised << block; end
 
+    # Service full_name is needed to route http requests to this service.
+    def full_name; self.class.service_full_name; end
+    def name; self.class.service_name; end
+
     # Rack app handler.
     def call(rack_env)
       begin
@@ -116,6 +65,23 @@ module Twirp
       end
     end
 
+    # Call the handler method with input attributes or protobuf object.
+    # Returns a proto object (response) or a Twirp::Error.
+    # Hooks are not called and exceptions are raised instead of being wrapped.
+    # This is useful for unit testing the handler. The env should include
+    # fake data that is used by the handler, replicating middleware and before hooks.
+    def call_rpc(rpc_method, input={}, env={})
+      base_env = self.class.rpcs[rpc_method.to_s]
+      return Twirp::Error.bad_route("Invalid rpc method #{rpc_method.to_s.inspect}") unless base_env
+
+      env = env.merge(base_env)
+      input = env[:input_class].new(input) if input.is_a? Hash
+      env[:input] = input
+      env[:content_type] ||= "application/protobuf"
+      env[:http_response_headers] = {}
+      call_handler(env)
+    end
+
 
   private
 
@@ -140,11 +106,11 @@ module Twirp
       end
       method_name = path_parts[-1]
 
-      base_env = self.class.base_envs[method_name]
+      base_env = self.class.rpcs[method_name]
       if !base_env
         return bad_route_error("Invalid rpc method #{method_name.inspect}", rack_request)
       end
-      env.merge!(base_env) # :rpc_method, :input_class, :output_class, :handler_method
+      env.merge!(base_env) # :rpc_method, :input_class, :output_class
 
       input = nil
       begin
@@ -162,35 +128,35 @@ module Twirp
       Twirp::Error.bad_route msg, twirp_invalid_route: "#{req.request_method} #{req.fullpath}"
     end
 
-    def decode_input(body, input_class, content_type)
+    def decode_input(bytes, input_class, content_type)
       case content_type
-      when "application/protobuf" then input_class.decode(body)
-      when "application/json"     then input_class.decode_json(body)
+      when "application/protobuf" then input_class.decode(bytes)
+      when "application/json"     then input_class.decode_json(bytes)
       end
     end
 
-    def encode_output(output, output_class, content_type)
+    def encode_output(obj, output_class, content_type)
       case content_type
-      when "application/protobuf" then output_class.encode(output)
-      when "application/json"     then output_class.encode_json(output)
+      when "application/protobuf" then output_class.encode(obj)
+      when "application/json"     then output_class.encode_json(obj)
       end
     end
 
     # Call handler method and return a Protobuf Message or a Twirp::Error.
     def call_handler(env)
-      handler_method = env[:handler_method]
-      if !@handler.respond_to?(handler_method)
-        return Twirp::Error.unimplemented("Handler method #{handler_method} is not implemented.")
+      m = env[:ruby_method]
+      if !@handler.respond_to?(m)
+        return Twirp::Error.unimplemented("Handler method #{m} is not implemented.")
       end
 
-      out = @handler.send(handler_method, env[:input], env)
+      out = @handler.send(m, env[:input], env)
       case out
       when env[:output_class], Twirp::Error
         out
       when Hash
         env[:output_class].new(out)
       else
-        Twirp::Error.internal("Handler method #{handler_method} expected to return one of #{env[:output_class].name}, Hash or Twirp::Error, but returned #{out.class.name}.")
+        Twirp::Error.internal("Handler method #{m} expected to return one of #{env[:output_class].name}, Hash or Twirp::Error, but returned #{out.class.name}.")
       end
     end
 

data/lib/twirp/service_dsl.rb

@@ -0,0 +1,61 @@
+module Twirp
+
+  module ServiceDSL
+
+    # Configure service package name.
+    def package(name)
+      @package = name
+    end
+
+    # Configure service name.
+    def service(name)
+      @service = name
+    end
+
+    # Configure service rpc methods.
+    def rpc(rpc_method, input_class, output_class, opts)
+      raise ArgumentError.new("rpc_method can not be empty") if rpc_method.to_s.empty?
+      raise ArgumentError.new("input_class must be a Protobuf Message class") unless input_class.is_a?(Class)
+      raise ArgumentError.new("output_class must be a Protobuf Message class") unless output_class.is_a?(Class)
+      raise ArgumentError.new("opts[:ruby_method] is mandatory") unless opts && opts[:ruby_method]
+
+      rpcdef = {
+        rpc_method: rpc_method.to_sym, # as defined in the Proto file.
+        input_class: input_class, # google/protobuf Message class to serialize the input (proto request).
+        output_class: output_class, # google/protobuf Message class to serialize the output (proto response).
+        ruby_method: opts[:ruby_method].to_sym, # method on the handler or client to handle this rpc requests.
+      }
+
+      @rpcs ||= {}
+      @rpcs[rpc_method.to_s] = rpcdef
+
+      rpc_define_method(rpcdef) if respond_to? :rpc_define_method # hook for the client to implement the methods on the class
+    end
+
+    # Get configured package name as String.
+    # An empty value means that there's no package.
+    def package_name
+      @package_name ||= @package.to_s
+    end
+
+    # Service name as String. Defaults to the class name.
+    def service_name
+      @service_name ||= (@service || self.name.split("::").last).to_s
+    end
+
+    # Service name with package prefix, which should uniquelly identifiy the service,
+    # for example "example.v3.Haberdasher" for package "example.v3" and service "Haberdasher".
+    # This can be used as a path prefix to route requests to the service, because a Twirp URL is:
+    # "#{base_url}/#{service_full_name}/#{method]"
+    def service_full_name
+      @service_full_name ||= package_name.empty? ? service_name : "#{package_name}.#{service_name}"
+    end
+
+    # Get raw definitions for rpc methods.
+    # This values are used as base env for handler methods.
+    def rpcs
+      @rpcs || {}
+    end
+
+  end
+end

data/lib/twirp/version.rb

@@ -1,3 +1,3 @@
 module Twirp
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/test/client_test.rb

@@ -0,0 +1,203 @@
+require 'minitest/autorun'
+require 'rack/mock'
+require 'google/protobuf'
+require 'json'
+
+require_relative '../lib/twirp'
+require_relative './fake_services'
+
+class ClientTest < Minitest::Test
+
+  def test_new_empty_client
+    c = EmptyClient.new("http://localhost:3000")
+    refute_nil c
+    refute_nil c.instance_variable_get(:@conn) # make sure that connection was assigned
+    assert_equal "EmptyClient", c.service_full_name
+  end
+
+  def test_new_with_invalid_url
+    assert_raises URI::InvalidURIError do
+      EmptyClient.new("lulz")
+    end
+  end
+
+  def test_new_with_invalid_faraday_connection
+    assert_raises ArgumentError do
+      EmptyClient.new(something: "else")
+    end
+  end
+
+  def test_call_rpc_success
+    c = FooClient.new(conn_stub("/Foo/Foo") {|req|
+      [200, protoheader, proto(Foo, foo: "out")]
+    })
+    resp = c.call_rpc(:Foo, foo: "in")
+    assert_nil resp.error
+    refute_nil resp.data
+    assert_equal "out", resp.data.foo
+  end
+
+  def test_call_rpc_error
+    c = FooClient.new(conn_stub("/Foo/Foo") {|req|
+      [400, {}, json(code: "invalid_argument", msg: "dont like empty")]
+    })
+    resp = c.call_rpc(:Foo, foo: "")
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :invalid_argument, resp.error.code
+    assert_equal "dont like empty", resp.error.msg
+  end
+
+  def test_call_rpc_serialization_exception
+    c = FooClient.new(conn_stub("/Foo/Foo") {|req|
+      [200, protoheader, "badstuff"]
+    })
+    assert_raises Google::Protobuf::ParseError do
+      resp = c.call_rpc(:Foo, foo: "in")
+    end
+  end
+
+  def test_call_rpc_invalid_method
+    c = FooClient.new("http://localhost")
+    resp = c.call_rpc(:OtherStuff, foo: "noo")
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :bad_route, resp.error.code
+  end
+
+  def test_success
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [200, protoheader, proto(Example::Hat, inches: 99, color: "red")]
+    })
+    resp = c.make_hat({})
+    assert_nil resp.error
+    assert_equal 99, resp.data.inches
+    assert_equal "red", resp.data.color
+  end
+
+  def test_serialized_request_body_attrs
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      size = Example::Size.decode(req.body) # body is valid protobuf
+      assert_equal 666, size.inches
+
+      [200, protoheader, proto(Example::Hat)]
+    })
+    resp = c.make_hat(inches: 666)
+    assert_nil resp.error
+    refute_nil resp.data
+  end
+
+  def test_serialized_request_body_proto
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      assert_equal "application/protobuf", req.request_headers['Content-Type']
+
+      size = Example::Size.decode(req.body) # body is valid protobuf
+      assert_equal 666, size.inches
+
+      [200, protoheader, proto(Example::Hat)]
+    })
+    resp = c.make_hat(Example::Size.new(inches: 666))
+    assert_nil resp.error
+    refute_nil resp.data
+  end
+
+  def test_twirp_error
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [500, {}, json(code: "internal", msg: "something went wrong")]
+    })
+    resp = c.make_hat(inches: 1)
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :internal, resp.error.code
+    assert_equal "something went wrong", resp.error.msg
+  end
+
+  def test_intermediary_plain_error
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [503, {}, 'plain text error from proxy']
+    })
+    resp = c.make_hat(inches: 1)
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :unavailable, resp.error.code # 503 maps to :unavailable
+    assert_equal "unavailable", resp.error.msg
+    assert_equal "true", resp.error.meta[:http_error_from_intermediary]
+    assert_equal "Response is not JSON", resp.error.meta[:not_a_twirp_error_because]
+    assert_equal "plain text error from proxy", resp.error.meta[:body]
+  end
+
+  def test_redirect_error
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [300, {'location' => "http://rainbow.com"}, '']
+    })
+    resp = c.make_hat(inches: 1)
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :internal, resp.error.code
+    assert_equal "Unexpected HTTP Redirect from location=http://rainbow.com", resp.error.msg
+    assert_equal "true", resp.error.meta[:http_error_from_intermediary]
+    assert_equal "Redirects not allowed on Twirp requests", resp.error.meta[:not_a_twirp_error_because]
+  end
+
+  def test_missing_proto_response_header
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [200, {}, proto(Example::Hat, inches: 99, color: "red")]
+    })
+    resp = c.make_hat({})
+    refute_nil resp.error
+    assert_equal :internal, resp.error.code
+    assert_equal 'Expected response Content-Type "application/protobuf" but found nil', resp.error.msg
+  end
+
+  def test_error_with_invalid_code
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [500, {}, json(code: "unicorn", msg: "the unicorn is here")]
+    })
+    resp = c.make_hat({})
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :internal, resp.error.code
+    assert_equal "Invalid Twirp error code: unicorn", resp.error.msg
+  end
+
+  def test_error_with_no_code
+    c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
+      [500, {}, json(msg: "I have no code of honor")]
+    })
+    resp = c.make_hat({})
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :unknown, resp.error.code # 500 maps to :unknown
+    assert_equal "unknown", resp.error.msg
+    assert_equal "true", resp.error.meta[:http_error_from_intermediary]
+    assert_equal 'Response is JSON but it has no "code" attribute', resp.error.meta[:not_a_twirp_error_because]
+    assert_equal '{"msg":"I have no code of honor"}', resp.error.meta[:body]
+  end
+
+
+  # Test Helpers
+  # ------------
+
+  def protoheader
+    {'Content-Type' => 'application/protobuf'}
+  end
+
+  def proto(clss, attrs={})
+    clss.encode(clss.new(attrs))
+  end
+
+  def json(attrs)
+    JSON.generate(attrs)
+  end
+
+  def conn_stub(path)
+    Faraday.new do |conn|
+      conn.adapter :test do |stub|
+        stub.post(path) do |env|
+          yield(env)
+        end
+      end
+    end
+  end
+
+end