twirp 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8be53839103af850b802185600fb7496556d3334
-  data.tar.gz: '08333f8e2be8996b92d9d25368eaa03d0470ef51'
+  metadata.gz: a30f71eb6c946fa8356d486b1decd82733bbb3af
+  data.tar.gz: db3c570238ac24017af314eedb327fd8f5f07bb0
 SHA512:
-  metadata.gz: d4a61196709d7b86207d20618046c87eed889cdb1d5f15693019aad4e25f7df2aecee842b17d2e546cd84212718301e5938fddd4fd274d7e982c6d5354ac6ce1
-  data.tar.gz: b51466076296ddc2a4ee33edfd4557c4236408786902556c77a49e478c0e0a71d4dd603e9a788a141e98739fe15ab252e62f00a96d3bae024386909e27f68aa7
+  metadata.gz: a59ff7c4ba349bce47e06a3a47d68eccfd411f43b63df34948593ab0d7987a596a766df398b633a8b31890cbadd09297c89d7619bd7fb1990d4538ae65c9c297
+  data.tar.gz: 39b024e1ba715058c2ad07c7b3e5942d0d3aae47960a02402b1f497c3bd6fdb1bdc6cd19c88005a8844238c2686e6d40251aeeeca13ed0cadb50f499f2c3c216

data/README.md

@@ -53,19 +53,19 @@ protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./example/hello_world/serv
 ```
 
 
-## Twirp Service
+## Twirp Service Handler
 
-A Twirp service delegates into a service handler to implement each rpc method. For example a handler for `HelloWorld`:
+A handler is a simple class that implements each rpc method. For example a handler for `HelloWorld`:
 
 ```ruby
 class HelloWorldHandler
 
   def hello(req, env)
     if req.name.empty?
-      Twirp::Error.invalid_argument("name is mandatory")
-    else
-      {message: "Hello #{req.name}"}
+      return Twirp::Error.invalid_argument("is mandatory", argument: "name")
     end
+
+    {message: "Hello #{req.name}"}
   end
 
 end
@@ -75,6 +75,21 @@ The `req` argument is the request message (input), and the returned value is exp
 
 The `env` argument contains metadata related to the request (e.g. `env[:output_class]`), and other fields that could have been set from before-hooks (e.g. `env[:user_id]` from authentication).
 
+
+### Start the Service
+
+The service is a [Rack app](https://rack.github.io/) instantiated with your handler impementation. For example:
+
+```ruby
+handler = HelloWorldHandler.new()
+service = Example::HelloWorldService.new(handler)
+
+require 'rack'
+Rack::Handler::WEBrick.run service
+```
+
+Rack apps can also be mounted as Rails routes (e.g. `mount service, at: service.full_name`) and are compatible with many other HTTP frameworks.
+
 ### Unit Tests
 
 Twirp already takes care of HTTP routing and serialization, you don't really need to test that part, insteadof that, focus on testing the handler using the method `.call_rpc(rpc_method, attrs={}, env={})` on the service:
@@ -102,33 +117,18 @@ end
 ```
 
 
-### Start the Service
-
-The service is a [Rack app](https://rack.github.io/) instantiated with your handler impementation. For example:
-
-```ruby
-handler = HelloWorldHandler.new()
-service = Example::HelloWorldService.new(handler)
-
-require 'rack'
-Rack::Handler::WEBrick.run service
-```
-
-Rack apps can also be mounted as Rails routes (e.g. `mount service, at: service.full_name`) and are compatible with many other HTTP frameworks.
-
-
 ## Twirp Clients
 
-Instantiate the client with the base_url:
+Clients implement the same methods as the service. For Example:
 
 ```ruby
 c = Example::HelloWorldClient.new("http://localhost:3000")
+resp = c.hello(name: "World") # serialized as Protobuf
 ```
 
-Clients implement the same methods as in the service and return a response object with `data` or `error`:
+The response object can have `data` or an `error`.
 
 ```ruby
-resp = c.hello(name: "World")
 if resp.error
   puts resp.error #=> <Twirp::Error code:... msg:"..." meta:{...}>
 else
@@ -136,9 +136,9 @@ else
 end
 ```
 
-### Configure Clients with Faraday
+#### Configure Clients with Faraday
 
-While Twirp takes care of routing, serialization and error handling, other advanced HTTP options can be configured with [Faraday](https://github.com/lostisland/faraday) middleware. For example:
+While Twirp takes care of routing, serialization and error handling, other advanced HTTP options can be configured with [Faraday](https://github.com/lostisland/faraday) middleware. Clients can be initialized with a Faraday connection:
 
 ```ruby
 conn = Faraday.new(:url => 'http://localhost:3000') do |c|
@@ -151,23 +151,22 @@ end
 c = Example::HelloWorldClient.new(conn)
 ```
 
-### Protobuf or JSON
+#### Protobuf or JSON
 
 Clients use Protobuf by default. To use JSON, set the `content_type` option as 2nd argument:
 
 ```ruby
-c = Example::HelloWorldClient.new("http://localhost:3000", content_type: "application/json")
+c = Example::HelloWorldClient.new(conn, content_type: "application/json")
 resp = c.hello(name: "World") # serialized as JSON
 ```
 
-### Add-hoc JSON requests
+#### Add-hoc JSON requests
 
 If you just want to make a few quick requests from the console, you can instantiate a plain client and make `.json` calls:
 
 ```ruby
-c = Twirp::Client.new("http://localhost:3000", package: "example", service: "HelloWorld")
-resp = c.json(:Hello, name: "World")
-puts resp.data["message"]
+c = Twirp::Client.new(conn, package: "example", service: "HelloWorld")
+resp = c.json(:Hello, name: "World") # serialized as JSON, resp.data is a Hash
 ```
 
 

data/lib/twirp/client.rb

@@ -11,21 +11,97 @@ module Twirp
     # DSL to define a client with package, service and rpcs.
     extend ServiceDSL
 
-    # DSL (alternative) to define a client from a Service class.
-    def self.client_for(svclass)
-      package svclass.package_name
-      service svclass.service_name
-      svclass.rpcs.each do |rpc_method, rpcdef|
-        rpc rpc_method, rpcdef[:input_class], rpcdef[:output_class], ruby_method: rpcdef[:ruby_method]
+    class << self # class methods
+
+      # DSL (alternative) to define a client from a Service class.
+      def client_for(svclass)
+        package svclass.package_name
+        service svclass.service_name
+        svclass.rpcs.each do |rpc_method, rpcdef|
+          rpc rpc_method, rpcdef[:input_class], rpcdef[:output_class], ruby_method: rpcdef[:ruby_method]
+        end
       end
-    end
 
-    # Hook for ServiceDSL#rpc to define a new method client.<ruby_method>(input, opts).
-    def self.rpc_define_method(rpcdef)
-      define_method rpcdef[:ruby_method] do |input|
-        rpc(rpcdef[:rpc_method], input)
+      # Hook for ServiceDSL#rpc to define a new method client.<ruby_method>(input, opts).
+      def rpc_define_method(rpcdef)
+        unless method_defined? rpcdef[:ruby_method] # collision with existing rpc method
+          define_method rpcdef[:ruby_method] do |input|
+            rpc(rpcdef[:rpc_method], input)
+          end
+        end
       end
-    end
+
+      def error_from_response(resp)
+        status = resp.status
+
+        if is_http_redirect? status
+          return twirp_redirect_error(status, resp.headers['Location'])
+        end
+
+        err_attrs = nil
+        begin
+          err_attrs = Encoding.decode_json(resp.body)
+        rescue JSON::ParserError
+          return twirp_error_from_intermediary(status, "Response is not JSON", resp.body)
+        end
+
+        code = err_attrs["code"]
+        if code.to_s.empty?
+          return twirp_error_from_intermediary(status, "Response is JSON but it has no \"code\" attribute", resp.body)
+        end
+        code = code.to_s.to_sym
+        if !Twirp::Error.valid_code?(code)
+          return Twirp::Error.internal("Invalid Twirp error code: #{code}", invalid_code: code.to_s, body: resp.body)
+        end
+
+        Twirp::Error.new(code, err_attrs["msg"], err_attrs["meta"])
+      end
+
+      # Error that was caused by an intermediary proxy like a load balancer.
+      # The HTTP errors code from non-twirp sources is mapped to equivalent twirp errors.
+      # The mapping is similar to gRPC: https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md.
+      # Returned twirp Errors have some additional metadata for inspection.
+      def twirp_error_from_intermediary(status, reason, body)
+        code = case status
+          when 400 then :internal
+          when 401 then :unauthenticated
+          when 403 then :permission_denied
+          when 404 then :bad_route
+          when 429, 502, 503, 504 then :unavailable
+          else :unknown
+        end
+
+        Twirp::Error.new(code, code.to_s, {
+          http_error_from_intermediary: "true",
+          not_a_twirp_error_because: reason,
+          status_code: status.to_s,
+          body: body.to_s,
+        })
+      end
+
+      # Twirp clients should not follow redirects automatically, Twirp only handles
+      # POST requests, redirects should only happen on GET and HEAD requests.
+      def twirp_redirect_error(status, location)
+        msg = "Unexpected HTTP Redirect from location=#{location}"
+        Twirp::Error.new(:internal, msg, {
+          http_error_from_intermediary: "true",
+          not_a_twirp_error_because: "Redirects not allowed on Twirp requests",
+          status_code: status.to_s,
+          location: location.to_s,
+        })
+      end
+
+      def is_http_redirect?(status)
+        status >= 300 && status <= 399
+      end
+
+      def rpc_path(service_full_name, rpc_method)
+        "/#{service_full_name}/#{rpc_method}"
+      end
+
+    end # class << self
+
+
 
     # Init with a Faraday connection, or a base_url that is used in a default connection.
     # Clients use Content-Type="application/protobuf" by default. For JSON clinets use :content_type => "application/json".
@@ -48,10 +124,6 @@ module Twirp
       end
     end
 
-    def rpc_path(rpc_method)
-      "/#{@service_full_name}/#{rpc_method}"
-    end
-
     # Make a remote procedure call to a defined rpc_method. The input can be a Proto message instance,
     # or the attributes (Hash) to instantiate it. Returns a ClientResp instance with an instance of
     # output_class, or a Twirp::Error. The input and output classes are the ones configued with the rpc DSL.
@@ -66,13 +138,13 @@ module Twirp
       body = Encoding.encode(input, rpcdef[:input_class], @content_type)
 
       resp = @conn.post do |r|
-        r.url rpc_path(rpc_method)
+        r.url "/#{@service_full_name}/#{rpc_method}"
         r.headers['Content-Type'] = @content_type
         r.body = body
       end
 
       if resp.status != 200
-        return ClientResp.new(nil, error_from_response(resp))
+        return ClientResp.new(nil, self.class.error_from_response(resp))
       end
 
       if resp.headers['Content-Type'] != @content_type
@@ -91,83 +163,18 @@ module Twirp
       body = Encoding.encode_json(attrs)
 
       resp = @conn.post do |r|
-        r.url rpc_path(rpc_method)
+        r.url "/#{@service_full_name}/#{rpc_method}"
         r.headers['Content-Type'] = Encoding::JSON
         r.body = body
       end
 
       if resp.status != 200
-        return ClientResp.new(nil, error_from_response(resp))
+        return ClientResp.new(nil, self.class.error_from_response(resp))
       end
 
       data = Encoding.decode_json(resp.body)
       return ClientResp.new(data, nil)
     end
-
-    def error_from_response(resp)
-      status = resp.status
-
-      if is_http_redirect? status
-        return twirp_redirect_error(status, resp.headers['Location'])
-      end
-
-      err_attrs = nil
-      begin
-        err_attrs = JSON.parse(resp.body)
-      rescue JSON::ParserError
-        return twirp_error_from_intermediary(status, "Response is not JSON", resp.body)
-      end
-
-      code = err_attrs["code"]
-      if code.to_s.empty?
-        return twirp_error_from_intermediary(status, "Response is JSON but it has no \"code\" attribute", resp.body)
-      end
-      code = code.to_s.to_sym
-      if !Twirp::Error.valid_code?(code)
-        return Twirp::Error.internal("Invalid Twirp error code: #{code}", invalid_code: code.to_s, body: resp.body)
-      end
-
-      Twirp::Error.new(code, err_attrs["msg"], err_attrs["meta"])
-    end
-
-    # Error that was caused by an intermediary proxy like a load balancer.
-    # The HTTP errors code from non-twirp sources is mapped to equivalent twirp errors.
-    # The mapping is similar to gRPC: https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md.
-    # Returned twirp Errors have some additional metadata for inspection.
-    def twirp_error_from_intermediary(status, reason, body)
-      code = case status
-        when 400 then :internal
-        when 401 then :unauthenticated
-        when 403 then :permission_denied
-        when 404 then :bad_route
-        when 429, 502, 503, 504 then :unavailable
-        else :unknown
-      end
-
-      Twirp::Error.new(code, code.to_s, {
-        http_error_from_intermediary: "true",
-        not_a_twirp_error_because: reason,
-        status_code: status.to_s,
-        body: body.to_s,
-      })
-    end
-
-    # Twirp clients should not follow redirects automatically, Twirp only handles
-    # POST requests, redirects should only happen on GET and HEAD requests.
-    def twirp_redirect_error(status, location)
-      msg = "Unexpected HTTP Redirect from location=#{location}"
-      Twirp::Error.new(:internal, msg, {
-        http_error_from_intermediary: "true",
-        not_a_twirp_error_because: "Redirects not allowed on Twirp requests",
-        status_code: status.to_s,
-        location: location.to_s,
-      })
-    end
-
-    def is_http_redirect?(status)
-      status >= 300 && status <= 399
-    end
-
   end
 
   class ClientResp

data/lib/twirp/version.rb

@@ -1,3 +1,3 @@
 module Twirp
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/test/client_test.rb

@@ -27,6 +27,28 @@ class ClientTest < Minitest::Test
     end
   end
 
+  def test_dsl_method_definition_collision
+    # To avoid collisions, the Twirp::Client class should have very few methods
+    mthds = Twirp::Client.instance_methods(false)
+    assert_equal [:json, :rpc], mthds
+
+    # If one of the methods is being implemented through the DSL, the colision should be avoided
+    num_mthds = EmptyClient.instance_methods.size
+    EmptyClient.rpc :Json, Example::Empty, Example::Empty, :ruby_method => :json
+    assert_equal num_mthds, EmptyClient.instance_methods.size # no new method was added (collision)
+
+    # Make sure that the previous .json method was not modified
+    c = EmptyClient.new(conn_stub("/EmptyClient/Json") {|req|
+      [200, {}, json(foo: "bar")]
+    })
+    resp = c.json(:Json, foo: "bar")
+    assert_equal "bar", resp.data["foo"]
+
+    # Adding any other rpc would work as expected
+    EmptyClient.rpc :Other, Example::Empty, Example::Empty, :ruby_method => :other
+    assert_equal num_mthds + 1, EmptyClient.instance_methods.size # new method added
+  end
+
 
   # Call .rpc on Protobuf client
   # ----------------------------

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twirp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Cyrus A. Forbes