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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 31b1acc1215a5040a22d6ef3715103a8aa6840c9
4
- data.tar.gz: 9cf27b5d6c7232bd6ccbeaf4b54211d97dc1cf45
3
+ metadata.gz: 7c112741e2caa5862500f4a8593d6d0aac78d26a
4
+ data.tar.gz: 607d5e0dbd7af7ac89c8e029885845462aad2578
5
5
  SHA512:
6
- metadata.gz: af3f533423755f9d9ea5e27194a7f7efc857f1dbc4268a3d08548315651b14564f63ea8533b061c9b3c3efc261200c74c7b108696d99905a4ea8eed3c5f47b96
7
- data.tar.gz: daf1b600b9df7240fbd99c1289be16f98f60ca0322ce23cfe9c3490611ecf99293d06a6b800ae8221f33c09cc1e0bbb65f536cfeab5b7d5beab678aaeb0590c5
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 `gem install twirp`.
9
+ Add `gem "twirp"` to your Gemfile, or install with
10
10
 
11
- For code generation, you also need [protoc](https://github.com/golang/protobuf) (version 3+).
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
- A Twirp service defines RPC methods to send and receive Protobuf messages. For example, a `HelloWorld` service:
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, which can also be defined from their DSL or auto-generated.
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. The service is a [Rack app](https://rack.github.io/). For example:
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
- 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.
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
 
@@ -96,8 +96,13 @@ module Twirp
96
96
  status >= 300 && status <= 399
97
97
  end
98
98
 
99
- def rpc_path(service_full_name, rpc_method)
100
- "/#{service_full_name}/#{rpc_method}"
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.post do |r|
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
@@ -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.post do |r|
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
@@ -1,3 +1,3 @@
1
1
  module Twirp
2
- VERSION = "0.5.0"
2
+ VERSION = "0.5.1"
3
3
  end
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.0
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-09 00:00:00.000000000 Z
12
+ date: 2018-04-13 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: google-protobuf