twirp 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a30f71eb6c946fa8356d486b1decd82733bbb3af
-  data.tar.gz: db3c570238ac24017af314eedb327fd8f5f07bb0
+  metadata.gz: 31b1acc1215a5040a22d6ef3715103a8aa6840c9
+  data.tar.gz: 9cf27b5d6c7232bd6ccbeaf4b54211d97dc1cf45
 SHA512:
-  metadata.gz: a59ff7c4ba349bce47e06a3a47d68eccfd411f43b63df34948593ab0d7987a596a766df398b633a8b31890cbadd09297c89d7619bd7fb1990d4538ae65c9c297
-  data.tar.gz: 39b024e1ba715058c2ad07c7b3e5942d0d3aae47960a02402b1f497c3bd6fdb1bdc6cd19c88005a8844238c2686e6d40251aeeeca13ed0cadb50f499f2c3c216
+  metadata.gz: af3f533423755f9d9ea5e27194a7f7efc857f1dbc4268a3d08548315651b14564f63ea8533b061c9b3c3efc261200c74c7b108696d99905a4ea8eed3c5f47b96
+  data.tar.gz: daf1b600b9df7240fbd99c1289be16f98f60ca0322ce23cfe9c3490611ecf99293d06a6b800ae8221f33c09cc1e0bbb65f536cfeab5b7d5beab678aaeb0590c5

data/README.md

@@ -55,7 +55,7 @@ protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./example/hello_world/serv
 
 ## Twirp Service Handler
 
-A handler is a simple class that implements each rpc method. For example a handler for `HelloWorld`:
+A handler implements the rpc methods. For example a handler for `HelloWorldService`:
 
 ```ruby
 class HelloWorldHandler
@@ -71,14 +71,16 @@ class HelloWorldHandler
 end
 ```
 
-The `req` argument is the request message (input), and the returned value is expected to be the response message, or a `Twirp::Error`.
+For each rpc method:
 
-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).
+ * The `req` argument is the input request message, already serialized.
+ * The `env` argument is the Twirp environment with data 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).
+ * The returned value is expected to be the response message (or its attributes), or a `Twirp::Error`.
 
 
-### Start the Service
+#### Start the Service
 
-The service is a [Rack app](https://rack.github.io/) instantiated with your handler impementation. For example:
+Instantiate the service with your handler impementation. The service is a [Rack app](https://rack.github.io/). For example:
 
 ```ruby
 handler = HelloWorldHandler.new()
@@ -90,7 +92,7 @@ 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
+#### 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:
 
@@ -119,26 +121,37 @@ end
 
 ## Twirp Clients
 
-Clients implement the same methods as the service. For Example:
+Instantiate a client with the service base url:
 
 ```ruby
-c = Example::HelloWorldClient.new("http://localhost:3000")
-resp = c.hello(name: "World") # serialized as Protobuf
+client = Example::HelloWorldClient.new("http://localhost:3000")
 ```
 
-The response object can have `data` or an `error`.
+Clients implement the same methods as the service handler. For example the client for `HelloWorldService` implements the `hello` method:
+
+```ruby
+resp = client.hello(name: "World")
+```
+
+As an alternative, in case that a service method collides with a Ruby method, you can always use the more general `.rpc` method:
+
+```ruby
+resp = client.rpc(:Hello, name: "World") # alternative
+```
+
+If the request fails, the response has an `error` with a `Twirp::Error`. If the request succeeds, the response has `data` with an instance of the response message class.
 
 ```ruby
 if resp.error
-  puts resp.error #=> <Twirp::Error code:... msg:"..." meta:{...}>
+  puts resp.error # <Twirp::Error code:... msg:"..." meta:{...}>
 else
-  puts resp.data #=> <Example::HelloResponse: message:"Hello World">
+  puts resp.data  # <Example::HelloResponse: message:"Hello World">
 end
 ```
 
 #### 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. Clients can be initialized with a Faraday connection:
+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. For example:
 
 ```ruby
 conn = Faraday.new(:url => 'http://localhost:3000') do |c|
@@ -148,25 +161,27 @@ conn = Faraday.new(:url => 'http://localhost:3000') do |c|
   c.use Faraday::Adapter::NetHttp # can use different HTTP libraries
 end
 
-c = Example::HelloWorldClient.new(conn)
+client = Example::HelloWorldClient.new(conn)
 ```
 
 #### Protobuf or JSON
 
-Clients use Protobuf by default. To use JSON, set the `content_type` option as 2nd argument:
+Protobuf is used by default. To serialize with JSON, set the `content_type` option as 2nd argument:
 
 ```ruby
-c = Example::HelloWorldClient.new(conn, content_type: "application/json")
-resp = c.hello(name: "World") # serialized as JSON
+client = Example::HelloWorldClient.new(conn, content_type: "application/json")
+resp = client.hello(name: "World") # serialized with JSON
 ```
 
 #### 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:
+If you just want to make a few quick requests from the console, you can make a `ClientJSON` instance. This doesn't require a service definition at all, but in the other hand, request and response values are not validated. Responses are just a Hash with attributes.
 
 ```ruby
-c = Twirp::Client.new(conn, package: "example", service: "HelloWorld")
-resp = c.json(:Hello, name: "World") # serialized as JSON, resp.data is a Hash
+require 'twirp'
+client = Twirp::ClientJSON.new(conn, package: "example", service: "HelloWorld")
+resp = client.rpc(:Hello, name: "World") # serialized with JSON
+puts resp # resp.data is a plain Hash
 ```
 
 
@@ -190,10 +205,10 @@ routing -> before -> handler
                      ! exception_raised -> on_error
 ```
 
-Hooks are setup in the service instance:
+Hooks are setup in the service instance. For example:
 
 ```ruby
-svc = Example::HelloWorld.new(handler)
+svc = Example::HelloWorldService.new(handler)
 
 svc.before do |rack_env, env|
   # Runs if properly routed to an rpc method, but before calling the method handler.

data/lib/twirp.rb

@@ -2,3 +2,4 @@ require_relative 'twirp/version'
 require_relative 'twirp/error'
 require_relative 'twirp/service'
 require_relative 'twirp/client'
+require_relative 'twirp/client_json'

data/lib/twirp/client.rb

@@ -1,5 +1,6 @@
 require 'faraday'
 
+require_relative 'client_resp'
 require_relative 'encoding'
 require_relative 'error'
 require_relative 'service_dsl'
@@ -117,11 +118,7 @@ module Twirp
         raise ArgumentError.new("Invalid content_type #{@content_type.inspect}. Expected one of #{Encoding.valid_content_types.inspect}")
       end
 
-      @service_full_name = if opts[:package] || opts[:service]
-        opts[:package].to_s.empty? ? opts[:service].to_s : "#{opts[:package]}.#{opts[:service]}"
-      else
-        self.class.service_full_name # defined through DSL
-      end
+      @service_full_name = self.class.service_full_name # defined through DSL
     end
 
     # Make a remote procedure call to a defined rpc_method. The input can be a Proto message instance,
@@ -140,6 +137,7 @@ module Twirp
       resp = @conn.post do |r|
         r.url "/#{@service_full_name}/#{rpc_method}"
         r.headers['Content-Type'] = @content_type
+        r.headers['Accept'] = @content_type
         r.body = body
       end
 
@@ -155,35 +153,5 @@ module Twirp
       return ClientResp.new(data, nil)
     end
 
-    # Convenience method to call any rpc method with dynamic json attributes.
-    # It is like .rpc but does not use the defined Protobuf messages to serialize/deserialize data;
-    # the request attrs can be anything and the response data is always a plain Hash of attributes.
-    # This is useful to test a service before doing any code-generation.
-    def json(rpc_method, attrs={})
-      body = Encoding.encode_json(attrs)
-
-      resp = @conn.post do |r|
-        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, self.class.error_from_response(resp))
-      end
-
-      data = Encoding.decode_json(resp.body)
-      return ClientResp.new(data, nil)
-    end
-  end
-
-  class ClientResp
-    attr_accessor :data
-    attr_accessor :error
-
-    def initialize(data, error)
-      @data = data
-      @error = error
-    end
   end
 end

data/lib/twirp/client_json.rb

@@ -0,0 +1,39 @@
+require_relative 'client'
+
+module Twirp
+
+  # Convenience class to call any rpc method with dynamic json attributes, without a service definition.
+  # This is useful to test a service before doing any code-generation.
+  class ClientJSON < Twirp::Client
+
+    def initialize(conn, opts={})
+      super(conn, opts)
+
+      package = opts[:package].to_s
+      service = opts[:service].to_s
+      raise ArgumentError.new("Missing option :service") if service.empty?
+      @service_full_name = package.empty? ? service : "#{package}.#{service}"
+    end
+
+    # This implementation does not use the defined Protobuf messages to serialize/deserialize data;
+    # the request attrs can be anything and the response data is always a plain Hash of attributes.
+    def rpc(rpc_method, attrs={})
+      body = Encoding.encode_json(attrs)
+
+      resp = @conn.post do |r|
+        r.url "/#{@service_full_name}/#{rpc_method}"
+        r.headers['Content-Type'] = Encoding::JSON
+        r.headers['Accept'] = Encoding::JSON
+        r.body = body
+      end
+
+      if resp.status != 200
+        return ClientResp.new(nil, self.class.error_from_response(resp))
+      end
+
+      data = Encoding.decode_json(resp.body)
+      return ClientResp.new(data, nil)
+    end
+
+  end
+end

data/lib/twirp/client_resp.rb

@@ -0,0 +1,11 @@
+module Twirp
+  class ClientResp
+    attr_accessor :data
+    attr_accessor :error
+
+    def initialize(data, error)
+      @data = data
+      @error = error
+    end
+  end
+end

data/lib/twirp/version.rb

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

data/test/client_json_test.rb

@@ -0,0 +1,67 @@
+require 'minitest/autorun'
+require 'rack/mock'
+require 'google/protobuf'
+require 'json'
+
+require_relative '../lib/twirp/client_json'
+require_relative './fake_services'
+
+class ClientJSONTest < Minitest::Test
+
+  def test_client_json_requires_service
+    assert_raises ArgumentError do
+      Twirp::ClientJSON.new("http://localhost:8080") # missing service
+    end
+    Twirp::ClientJSON.new("http://localhost:8080", service: "FooBar") # ok
+  end
+
+  def test_client_json_success
+    c = Twirp::ClientJSON.new(conn_stub("/my.pkg.Talking/Blah") {|req|
+      assert_equal "application/json", req.request_headers['Content-Type']
+      assert_equal "application/json", req.request_headers['Accept']
+      assert_equal '{"blah1":1,"blah2":2}', req.body # body is json
+
+      [200, {}, '{"blah_resp": 3}']
+    }, package: "my.pkg", service: "Talking")
+
+    resp = c.rpc :Blah, blah1: 1, blah2: 2
+    assert_nil resp.error
+    refute_nil resp.data
+    assert_equal 3, resp.data["blah_resp"]
+  end
+
+  def test_client_json_error
+    c = Twirp::ClientJSON.new(conn_stub("/Foo/Foomo") {|req|
+      [400, {}, '{"code": "invalid_argument", "msg": "dont like empty"}']
+    }, service: "Foo")
+
+    resp = c.rpc :Foomo, 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_client_bad_json_route
+    c = Twirp::ClientJSON.new(conn_stub("/Foo/OtherMethod") {|req|
+      [404, {}, 'not here buddy']
+    }, service: "Foo")
+
+    resp = c.rpc :OtherMethod, foo: ""
+    assert_nil resp.data
+    refute_nil resp.error
+    assert_equal :bad_route, resp.error.code
+  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

data/test/client_test.rb

@@ -9,7 +9,7 @@ require_relative './fake_services'
 class ClientTest < Minitest::Test
 
   def test_new_empty_client
-    c = EmptyClient.new("http://localhost:3000")
+    c = EmptyClient.new("http://localhost:8080")
     refute_nil c
     refute_nil c.instance_variable_get(:@conn) # make sure that connection was assigned
     assert_equal "EmptyClient", c.instance_variable_get(:@service_full_name)
@@ -27,22 +27,31 @@ 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
+  def test_dsl_rpc_method_definition_collisions
+    # To avoid collisions, the Twirp::Client class should only have the rpc method.
+    assert_equal [:rpc], Twirp::Client.instance_methods(false)
 
-    # If one of the methods is being implemented through the DSL, the colision should be avoided
+    # If one of the methods is being implemented through the DSL, the colision should be avoided, keeping the previous method.
     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)
+    EmptyClient.rpc :Rpc, Example::Empty, Example::Empty, :ruby_method => :rpc
+    assert_equal num_mthds, EmptyClient.instance_methods.size # no new method was added (is a collision)
 
-    # Make sure that the previous .json method was not modified
-    c = EmptyClient.new(conn_stub("/EmptyClient/Json") {|req|
-      [200, {}, json(foo: "bar")]
+    # Make sure that the previous .rpc method was not modified
+    c = EmptyClient.new(conn_stub("/EmptyClient/Rpc") {|req|
+      [200, protoheader, proto(Example::Empty, {})]
     })
-    resp = c.json(:Json, foo: "bar")
-    assert_equal "bar", resp.data["foo"]
+    resp = c.rpc(:Rpc, {})
+    assert_nil resp.error
+    refute_nil resp.data
+
+    # Adding a method that would override super-class methods like .to_s should also be avoided.
+    EmptyClient.rpc :ToString, Example::Empty, Example::Empty, :ruby_method => :to_s
+    assert_equal num_mthds, EmptyClient.instance_methods.size # no new method was added (is a collision)
+
+    # Make sure that the previous .to_s method was not modified
+    c = EmptyClient.new("http://localhost:8080")
+    resp = c.to_s
+    assert_equal String, resp.class
 
     # Adding any other rpc would work as expected
     EmptyClient.rpc :Other, Example::Empty, Example::Empty, :ruby_method => :other
@@ -78,6 +87,7 @@ class ClientTest < Minitest::Test
   def test_proto_serialized_request_body
     c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
       assert_equal "application/protobuf", req.request_headers['Content-Type']
+      assert_equal "application/protobuf", req.request_headers['Accept']
 
       size = Example::Size.decode(req.body) # body is valid protobuf
       assert_equal 666, size.inches
@@ -179,6 +189,7 @@ class ClientTest < Minitest::Test
   def test_json_serialized_request_body_attrs
     c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
       assert_equal "application/json", req.request_headers['Content-Type']
+      assert_equal "application/json", req.request_headers['Accept']
       assert_equal '{"inches":666}', req.body # body is valid json
       [200, jsonheader, '{}']
     }, content_type: "application/json")
@@ -191,6 +202,7 @@ class ClientTest < Minitest::Test
   def test_json_serialized_request_body_object
     c = Example::HaberdasherClient.new(conn_stub("/example.Haberdasher/MakeHat") {|req|
       assert_equal "application/json", req.request_headers['Content-Type']
+      assert_equal "application/json", req.request_headers['Accept']
       assert_equal '{"inches":666}', req.body # body is valid json
       [200, jsonheader, '{}']
     }, content_type: "application/json")
@@ -265,46 +277,6 @@ class ClientTest < Minitest::Test
     assert_equal :bad_route, resp.error.code
   end
 
-  # Call .json
-  # ----------
-
-  def test_direct_json_success
-    c = Twirp::Client.new(conn_stub("/my.pkg.Talking/Blah") {|req|
-      assert_equal "application/json", req.request_headers['Content-Type']
-      assert_equal '{"blah1":1,"blah2":2}', req.body # body is json
-
-      [200, {}, json(blah_resp: 3)]
-    }, package: "my.pkg", service: "Talking")
-
-    resp = c.json :Blah, blah1: 1, blah2: 2
-    assert_nil resp.error
-    refute_nil resp.data
-    assert_equal 3, resp.data["blah_resp"]
-  end
-
-  def test_direct_json_error
-    c = Twirp::Client.new(conn_stub("/Foo/Foomo") {|req|
-      [400, {}, json(code: "invalid_argument", msg: "dont like empty")]
-    }, service: "Foo")
-
-    resp = c.json :Foomo, 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_direct_json_bad_route
-    c = Twirp::Client.new(conn_stub("/Foo/OtherMethod") {|req|
-      [404, {}, 'not here buddy']
-    }, service: "Foo")
-
-    resp = c.json :OtherMethod, foo: ""
-    assert_nil resp.data
-    refute_nil resp.error
-    assert_equal :bad_route, resp.error.code
-  end
-
 
   # Test Helpers
   # ------------

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twirp
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Cyrus A. Forbes
@@ -73,11 +73,14 @@ files:
 - README.md
 - lib/twirp.rb
 - lib/twirp/client.rb
+- lib/twirp/client_json.rb
+- lib/twirp/client_resp.rb
 - lib/twirp/encoding.rb
 - lib/twirp/error.rb
 - lib/twirp/service.rb
 - lib/twirp/service_dsl.rb
 - lib/twirp/version.rb
+- test/client_json_test.rb
 - test/client_test.rb
 - test/error_test.rb
 - test/fake_services.rb
@@ -108,6 +111,7 @@ signing_key:
 specification_version: 4
 summary: Twirp services in Ruby.
 test_files:
+- test/client_json_test.rb
 - test/client_test.rb
 - test/error_test.rb
 - test/fake_services.rb