twirp 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +36 -35
- data/lib/twirp/client.rb +8 -9
- data/lib/twirp/client_json.rb +1 -7
- data/lib/twirp/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 7c112741e2caa5862500f4a8593d6d0aac78d26a
|
4
|
+
data.tar.gz: 607d5e0dbd7af7ac89c8e029885845462aad2578
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: fb48c7b88bbf255a9fe8addd04918e2f9d13218a2352385d5c247797e6fb5440c008bdd89a64f346800bb16b17c7e5717ed463dbf0269dca5ce01bd8281b16e5
|
7
|
+
data.tar.gz: a44529c441232b6987173600206c4a50a8f2c5d12381669b5f92ae63d4814a1d7406138df2e02c89b0587e0bf61399804ce8e4f4e69d17465908fb261f5cbfa7
|
data/README.md
CHANGED
@@ -6,17 +6,34 @@ The [Twirp protocol](https://twitchtv.github.io/twirp/docs/spec_v5.html) is impl
|
|
6
6
|
|
7
7
|
## Install
|
8
8
|
|
9
|
-
Add `gem "twirp"` to your Gemfile, or install with
|
9
|
+
Add `gem "twirp"` to your Gemfile, or install with
|
10
10
|
|
11
|
-
|
11
|
+
```
|
12
|
+
gem install twirp
|
13
|
+
```
|
14
|
+
|
15
|
+
Code generation works with [protoc](https://github.com/golang/protobuf) (the protobuf compiler)
|
16
|
+
using the `--ruby_out` option to generate messages and `--twirp_ruby_out` to generate services and clients. Make sure to install `protoc` version 3+.
|
17
|
+
|
18
|
+
Then use `go get` (Golang) to install the ruby_twirp protoc plugin:
|
19
|
+
|
20
|
+
```sh
|
21
|
+
go get -u github.com/cyrusaf/ruby-twirp/protoc-gen-twirp_ruby
|
22
|
+
```
|
23
|
+
|
24
|
+
## Code Generation
|
25
|
+
|
26
|
+
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:
|
27
|
+
|
28
|
+
```sh
|
29
|
+
protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./example/hello_world/service.proto
|
30
|
+
```
|
12
31
|
|
13
32
|
## Service DSL
|
14
33
|
|
15
|
-
|
34
|
+
The generated code makes use of the service DSL. For example, the generated code for the `HelloWorld` service looks like this:
|
16
35
|
|
17
36
|
```ruby
|
18
|
-
require 'twirp'
|
19
|
-
|
20
37
|
module Example
|
21
38
|
class HelloWorldService < Twirp::Service
|
22
39
|
package "example"
|
@@ -30,27 +47,7 @@ module Example
|
|
30
47
|
end
|
31
48
|
```
|
32
49
|
|
33
|
-
The `HelloRequest` and `HelloResponse` messages are expected to be [google-protobuf](https://github.com/google/protobuf/tree/master/ruby) messages
|
34
|
-
|
35
|
-
|
36
|
-
## Code Generation
|
37
|
-
|
38
|
-
RPC messages and the service definition can be auto-generated form a `.proto` file.
|
39
|
-
|
40
|
-
Code generation works with [protoc](https://github.com/golang/protobuf) (the protobuf compiler)
|
41
|
-
using the `--ruby_out` option to generate messages and `--twirp_ruby_out` to generate services and clients.
|
42
|
-
|
43
|
-
Make sure to install `protoc` (version 3+). Then use `go get` (Golang) to install the ruby_twirp protoc plugin:
|
44
|
-
|
45
|
-
```sh
|
46
|
-
go get -u github.com/cyrusaf/ruby-twirp/protoc-gen-twirp_ruby
|
47
|
-
```
|
48
|
-
|
49
|
-
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:
|
50
|
-
|
51
|
-
```sh
|
52
|
-
protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./example/hello_world/service.proto
|
53
|
-
```
|
50
|
+
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.
|
54
51
|
|
55
52
|
|
56
53
|
## Twirp Service Handler
|
@@ -80,17 +77,23 @@ For each rpc method:
|
|
80
77
|
|
81
78
|
#### Start the Service
|
82
79
|
|
83
|
-
Instantiate the service with your handler impementation.
|
80
|
+
Instantiate the service with your handler impementation. Here is where you would use dependency injection or any other extra setup.
|
84
81
|
|
85
82
|
```ruby
|
86
83
|
handler = HelloWorldHandler.new()
|
87
84
|
service = Example::HelloWorldService.new(handler)
|
85
|
+
```
|
88
86
|
|
87
|
+
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":
|
88
|
+
|
89
|
+
```ruby
|
89
90
|
require 'rack'
|
90
|
-
Rack::Handler::WEBrick.run service
|
91
|
-
```
|
92
91
|
|
93
|
-
|
92
|
+
path_prefix = "/twirp/" + service.full_name
|
93
|
+
server = WEBrick::HTTPServer.new(Port: 3000)
|
94
|
+
server.mount path_prefix, Rack::Handler::WEBrick, service
|
95
|
+
server.start
|
96
|
+
```
|
94
97
|
|
95
98
|
#### Unit Tests
|
96
99
|
|
@@ -124,7 +127,7 @@ end
|
|
124
127
|
Instantiate a client with the service base url:
|
125
128
|
|
126
129
|
```ruby
|
127
|
-
client = Example::HelloWorldClient.new("http://localhost:3000")
|
130
|
+
client = Example::HelloWorldClient.new("http://localhost:3000/twirp")
|
128
131
|
```
|
129
132
|
|
130
133
|
Clients implement the same methods as the service handler. For example the client for `HelloWorldService` implements the `hello` method:
|
@@ -154,7 +157,7 @@ end
|
|
154
157
|
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:
|
155
158
|
|
156
159
|
```ruby
|
157
|
-
conn = Faraday.new(:url => 'http://localhost:3000') do |c|
|
160
|
+
conn = Faraday.new(:url => 'http://localhost:3000/twirp') do |c|
|
158
161
|
c.use Faraday::Request::Retry
|
159
162
|
c.use Faraday::Request::BasicAuthentication, 'login', 'pass'
|
160
163
|
c.use Faraday::Response::Logger # log to STDOUT
|
@@ -178,10 +181,8 @@ resp = client.hello(name: "World") # serialized with JSON
|
|
178
181
|
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.
|
179
182
|
|
180
183
|
```ruby
|
181
|
-
require 'twirp'
|
182
184
|
client = Twirp::ClientJSON.new(conn, package: "example", service: "HelloWorld")
|
183
|
-
resp = client.rpc(:Hello, name: "World") # serialized with JSON
|
184
|
-
puts resp # resp.data is a plain Hash
|
185
|
+
resp = client.rpc(:Hello, name: "World") # serialized with JSON, resp.data is a plain Hash
|
185
186
|
```
|
186
187
|
|
187
188
|
|
data/lib/twirp/client.rb
CHANGED
@@ -96,8 +96,13 @@ module Twirp
|
|
96
96
|
status >= 300 && status <= 399
|
97
97
|
end
|
98
98
|
|
99
|
-
def
|
100
|
-
|
99
|
+
def make_http_request(conn, service_full_name, rpc_method, content_type, body)
|
100
|
+
conn.post do |r|
|
101
|
+
r.url "#{service_full_name}/#{rpc_method}"
|
102
|
+
r.headers['Content-Type'] = content_type
|
103
|
+
r.headers['Accept'] = content_type
|
104
|
+
r.body = body
|
105
|
+
end
|
101
106
|
end
|
102
107
|
|
103
108
|
end # class << self
|
@@ -134,13 +139,7 @@ module Twirp
|
|
134
139
|
input = rpcdef[:input_class].new(input) if input.is_a? Hash
|
135
140
|
body = Encoding.encode(input, rpcdef[:input_class], @content_type)
|
136
141
|
|
137
|
-
resp = @conn
|
138
|
-
r.url "/#{@service_full_name}/#{rpc_method}"
|
139
|
-
r.headers['Content-Type'] = @content_type
|
140
|
-
r.headers['Accept'] = @content_type
|
141
|
-
r.body = body
|
142
|
-
end
|
143
|
-
|
142
|
+
resp = self.class.make_http_request(@conn, @service_full_name, rpc_method, @content_type, body)
|
144
143
|
if resp.status != 200
|
145
144
|
return ClientResp.new(nil, self.class.error_from_response(resp))
|
146
145
|
end
|
data/lib/twirp/client_json.rb
CHANGED
@@ -20,13 +20,7 @@ module Twirp
|
|
20
20
|
def rpc(rpc_method, attrs={})
|
21
21
|
body = Encoding.encode_json(attrs)
|
22
22
|
|
23
|
-
resp = @conn
|
24
|
-
r.url "/#{@service_full_name}/#{rpc_method}"
|
25
|
-
r.headers['Content-Type'] = Encoding::JSON
|
26
|
-
r.headers['Accept'] = Encoding::JSON
|
27
|
-
r.body = body
|
28
|
-
end
|
29
|
-
|
23
|
+
resp = self.class.make_http_request(@conn, @service_full_name, rpc_method, Encoding::JSON, body)
|
30
24
|
if resp.status != 200
|
31
25
|
return ClientResp.new(nil, self.class.error_from_response(resp))
|
32
26
|
end
|
data/lib/twirp/version.rb
CHANGED
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: twirp
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.5.
|
4
|
+
version: 0.5.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Cyrus A. Forbes
|
@@ -9,7 +9,7 @@ authors:
|
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2018-04-
|
12
|
+
date: 2018-04-13 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: google-protobuf
|