twirp 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1465cef8ea8070380498d84e1678ef5edd495a6e
-  data.tar.gz: 97dda993421db600ef94146eede425f198f22145
+  metadata.gz: b8d83ed2c83e7cebf51801f40168dc7605e9e5be
+  data.tar.gz: cb2ce6ebc8517f887dfc4db4015f612330b85b8b
 SHA512:
-  metadata.gz: 206d4febd931eb71b6cbccf555bbd05edf53d74104a9bcec72676298c49b38a6c1cb390efeb489fd7271fc4504c76276d9f588fba6bada377e83a0d706a7837a
-  data.tar.gz: 230f965eeca4501b4618acc32cb7ccc89563831b9d70c621b5c05c88a4c180e86d0b98ee4fe7dca3805faa13583e72ca66d3666f761f49fa4d67e6ed25d14cf1
+  metadata.gz: ca5336f98853c5b86a85e60f5757f6c259d43c9635092937e40edd5f77b2e7756e7f7144335a9b3bb4a8e17f2d00dbccbd6aff52703f24beddb2c58fb471d254
+  data.tar.gz: 20c0c0f7b52e6e6fb041cdc9ec818ea096ce52535df779969c979fe450036a31bcfff031c9e89df02372e9cdcbf9ee5d6b0809734c2e80795bb06134a712526a

data/README.md

@@ -1,245 +1,15 @@
-# Twirp
+# Twirp-Ruby
 
-Twirp allows to easily define RPC services and clients that communicate using Protobuf or JSON over HTTP.
+[Twirp is a protocol](https://twitchtv.github.io/twirp/docs/spec_v5.html) for routing and serialization of services defined in a [.proto file](https://developers.google.com/protocol-buffers/docs/proto3), allowing easy implementation of RPC services with auto-generated clients in different languages.
 
-The [Twirp protocol](https://twitchtv.github.io/twirp/docs/spec_v5.html) is implemented in multiple languages. This means that you can write your service in one language and automatically generate clients in other languages. Refer to the [Golang implementation](https://github.com/twitchtv/twirp) for more details on the project.
+The [cannonical implementation](https://github.com/twitchtv/twirp) is in Golang. The Twirp-Ruby project in this repository is the Ruby implementation.
 
-## Install
-
-Add `gem "twirp"` to your Gemfile, or install with
-
-```
-gem install twirp
-```
-
-Code generation works with [protoc](https://github.com/golang/protobuf) (the protobuf compiler)
-using the `--ruby_out` option to generate messages and `--twirp_ruby_out` to generate services and clients. Make sure to install `protoc` version 3+.
-
-Then use `go get` (Golang) to install the ruby_twirp protoc plugin:
-
-```sh
-go get -u github.com/cyrusaf/ruby-twirp/protoc-gen-twirp_ruby
-```
-
-## Code Generation
-
-Service and client definitions can be auto-generated form a `.proto` file. For example, given a [Protobuf](https://developers.google.com/protocol-buffers/docs/proto3) file like [example/hello_world/service.proto](example/hello_world/service.proto), you can auto-generate proto and twirp files with the command:
-
-```sh
-protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./example/hello_world/service.proto
-```
-
-## Service DSL
-
-The generated code makes use of the service DSL. For example, the generated code for the `HelloWorld` service looks like this:
-
-```ruby
-module Example
-  class HelloWorldService < Twirp::Service
-    package "example"
-    service "HelloWorld"
-    rpc :Hello, HelloRequest, HelloResponse, :ruby_method => :hello
-  end
-
-  class HelloWorldClient < Twirp::Client
-    client_for HelloWorldService
-  end
-end
-```
-
-The `HelloRequest` and `HelloResponse` messages are expected to be [google-protobuf](https://github.com/google/protobuf/tree/master/ruby) messages. They are generated by `protoc`, but could also be defined from their DSL.
-
-
-## Twirp Service Handler
-
-A handler implements the rpc methods. For example a handler for `HelloWorldService`:
-
-```ruby
-class HelloWorldHandler
-
-  def hello(req, env)
-    if req.name.empty?
-      return Twirp::Error.invalid_argument("is mandatory", argument: "name")
-    end
-
-    {message: "Hello #{req.name}"}
-  end
-
-end
-```
-
-For each rpc method:
-
- * 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
-
-Instantiate the service with your handler impementation. Here is where you would use dependency injection or any other extra setup.
-
-```ruby
-handler = HelloWorldHandler.new()
-service = Example::HelloWorldService.new(handler)
-```
-
-The service is a [Rack app](https://rack.github.io/), it be mounted in a Rails app (e.g. in /config/routes.rb: `mount service, at: service.full_name`). And are also compatible with many other HTTP frameworks. For example, to mount on Webrick with base_url "http://localhost:3000/twirp":
-
-```ruby
-require 'rack'
-
-path_prefix = "/twirp/" + service.full_name
-server = WEBrick::HTTPServer.new(Port: 3000)
-server.mount path_prefix, Rack::Handler::WEBrick, service
-server.start
-```
-
-#### 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:
-
-```ruby
-require 'minitest/autorun'
-
-class HelloWorldHandlerTest < Minitest::Test
-
-  def test_hello_responds_with_name
-    resp = service.call_rpc :Hello, name: "World"
-    assert_equal "Hello World", resp.message
-  end
 
-  def test_hello_name_is_mandatory
-    twerr = service.call_rpc :Hello, name: ""
-    assert_equal :invalid_argument, twerr.code
-  end
-
-  def service
-    handler = HelloWorldHandler.new()
-    Example::HelloWorldService.new(handler)
-  end
-end
-```
-
-
-## Twirp Clients
-
-Instantiate a client with the service base url:
-
-```ruby
-client = Example::HelloWorldClient.new("http://localhost:3000/twirp")
-```
-
-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:{...}>
-else
-  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. For example:
-
-```ruby
-conn = Faraday.new(:url => 'http://localhost:3000/twirp') do |c|
-  c.use Faraday::Request::Retry
-  c.use Faraday::Request::BasicAuthentication, 'login', 'pass'
-  c.use Faraday::Response::Logger # log to STDOUT
-  c.use Faraday::Adapter::NetHttp # can use different HTTP libraries
-end
-
-client = Example::HelloWorldClient.new(conn)
-```
-
-#### Protobuf or JSON
-
-Protobuf is used by default. To serialize with JSON, set the `content_type` option as 2nd argument:
-
-```ruby
-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 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
-client = Twirp::ClientJSON.new(conn, package: "example", service: "HelloWorld")
-resp = client.rpc(:Hello, name: "World") # serialized with JSON, resp.data is a plain Hash
-```
-
-
-## Server Hooks
-
-In the lifecycle of a server request, Twirp starts by routing the request to a valid RPC method. If routing fails, the `on_error` hook is called with a bad_route error. If routing succeeds, the `before` hook is called before calling the RPC method handler, and then either `on_success` or `on_error` depending if the response is a Twirp error or not.
-
-```
-routing -> before -> handler -> on_success
-                             -> on_error
-```
-
-On every request, one and only one of `on_success` or `on_error` is called.
-
-
-If exceptions are raised, the `exception_raised` hook is called. The exceptioni is wrapped with an internal Twirp error, and if the `on_error` hook was not called yet, then it is called with the wrapped exception.
-
-
-```
-routing -> before -> handler
-                     ! exception_raised -> on_error
-```
-
-Hooks are setup in the service instance. For example:
-
-```ruby
-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.
-  # This is the only place to read the Rack env to access http request and middleware data.
-  # The Twirp env has the same routing info as in the handler method, e.g. :rpc_method, :input and :input_class.
-  # Returning a Twirp::Error here cancels the request, and the error is returned instead.
-  # If an exception is raised, the exception_raised hook will be called followed by on_error.
-  env[:user_id] = authenticate(rack_env)
-end
+## Install
 
-svc.on_success do |env|
-  # Runs after the rpc method is handled, if it didn't return Twirp errors or raised exceptions.
-  # The env[:output] contains the serialized message of class env[:ouput_class].
-  # If an exception is raised, the exception_raised hook will be called.
-  success_count += 1
-end
+Add `gem "twirp"` to your Gemfile, or install with `gem install twirp`.
 
-svc.on_error do |twerr, env|
-  # Runs on error responses, that is:
-  #  * bad_route errors
-  #  * before filters returning Twirp errors or raising exceptions.
-  #  * hander methods returning Twirp errors or raising exceptions.
-  # Raised exceptions are wrapped with Twirp::Error.internal_with(e).
-  # If an exception is raised here, the exception_raised hook will be called.
-  error_count += 1
-end
 
-svc.exception_raised do |e, env|
-  # Runs if an exception was raised from the handler or any of the hooks.
-  puts "[Error] #{e}\n#{e.backtrace.join("\n")}"
-end
-```
+## Documentation
 
+[Go to the Wiki](https://github.com/twitchtv/twirp-ruby/wiki).

data/lib/twirp.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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_relative 'twirp/version'
 require_relative 'twirp/error'
 require_relative 'twirp/service'

data/lib/twirp/client.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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 'faraday'
 
 require_relative 'client_resp'

data/lib/twirp/client_json.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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_relative 'client'
 
 module Twirp

data/lib/twirp/client_resp.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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.
+
 module Twirp
   class ClientResp
     attr_accessor :data

data/lib/twirp/encoding.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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 Twirp

data/lib/twirp/error.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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.
+
 module Twirp
 
   # Valid Twirp error codes and their mapping to related HTTP status.

data/lib/twirp/service.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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_relative 'encoding'
 require_relative 'error'
 require_relative 'service_dsl'

data/lib/twirp/service_dsl.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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.
+
 module Twirp
 
   module ServiceDSL

data/lib/twirp/version.rb

@@ -1,3 +1,16 @@
+# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file 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.
+
 module Twirp
-  VERSION = "0.5.2"
+  VERSION = "1.0.0"
 end

data/test/license_header_test.rb

@@ -0,0 +1,37 @@
+require 'minitest/autorun'
+
+# Check that all .rb files in /lib have the license header.
+class LicenseHeaderTest < Minitest::Test
+
+  LICENSE_HEADER_LINES = [
+    "# Copyright 2018 Twitch Interactive, Inc.  All Rights Reserved.",
+    "#",
+    "# Licensed under the Apache License, Version 2.0 (the \"License\"). You may not",
+    "# use this file except in compliance with the License. A copy of the License is",
+    "# located at",
+    "#",
+    "#     http://www.apache.org/licenses/LICENSE-2.0",
+    "#",
+    "# or in the \"license\" file accompanying this file. This file 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.",
+  ]
+
+  def test_files_have_license_header
+    test_dir = File.dirname(__FILE__)
+
+    files = Dir.glob("#{test_dir}/../lib/**/*.rb")
+    assert_operator files.size, :>, 1, "at least one file was loaded, otherwise the glob expression may be failing"
+
+    files.each do |filepath|
+      lines = File.read(filepath).split("\n")
+      assert_operator lines.size, :>, LICENSE_HEADER_LINES.size, "has license header"
+      LICENSE_HEADER_LINES.each_with_index do |license_line, i|
+        file_line = lines[i]
+        assert_equal license_line, file_line
+      end
+    end
+  end
+
+end

data/twirp.gemspec

@@ -11,15 +11,15 @@ Gem::Specification.new do |spec|
   spec.email         = ["forbescyrus@gmail.com", "tothemario@gmail.com"]
   spec.summary       = %q{Twirp services in Ruby.}
   spec.description   = %q{Twirp is a simple RPC framework with protobuf service definitions. The Twirp gem provides native support for Ruby.}
-  spec.homepage      = "https://github.com/cyrusaf/ruby-twirp"
+  spec.homepage      = "https://github.com/twitchtv/twirp-ruby"
   spec.license       = "MIT"
 
   spec.files         = Dir['lib/**/*'] + %w(Gemfile LICENSE README.md twirp.gemspec)
   spec.test_files    = Dir['test/**/*']
   spec.require_paths = ["lib"]
 
+  spec.required_ruby_version = '>= 1.9'
   spec.add_runtime_dependency 'google-protobuf', '~> 3.0', '>= 3.0.0'
-  spec.add_runtime_dependency 'faraday', '~> 0'
-
+  spec.add_runtime_dependency 'faraday', '~> 0' # for clients
   spec.add_development_dependency 'bundler', '~> 1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twirp
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Cyrus A. Forbes
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-13 00:00:00.000000000 Z
+date: 2018-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -84,9 +84,10 @@ files:
 - test/client_test.rb
 - test/error_test.rb
 - test/fake_services.rb
+- test/license_header_test.rb
 - test/service_test.rb
 - twirp.gemspec
-homepage: https://github.com/cyrusaf/ruby-twirp
+homepage: https://github.com/twitchtv/twirp-ruby
 licenses:
 - MIT
 metadata: {}
@@ -98,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '1.9'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -115,4 +116,5 @@ test_files:
 - test/client_test.rb
 - test/error_test.rb
 - test/fake_services.rb
+- test/license_header_test.rb
 - test/service_test.rb