rails_respond_to_pb 0.1.0 → 0.1.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.gitignore +1 -0
- data/CHANGELOG.md +1 -1
- data/README.md +158 -10
- data/docker-compose.yml +4 -0
- data/lib/rails_respond_to_pb/version.rb +1 -1
- data/rails_respond_to_pb.gemspec +3 -1
- metadata +32 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 1c322c035c9d8609dc8627e797c78c18a180646114ca046e712de5c602833471
|
4
|
+
data.tar.gz: 4620238b1f729bf8afff9f914e89c66d2f28fd19527012bbbd292302cd5da68d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 2e46f10d9b60f0670413af3683d9ef4ad72d6f84ac1e7773d2bb690ac8e62273e8f48d4de3bd0dc8db2296c7a2eb661d2380945f1a3dec45fa4408392da4a7a8
|
7
|
+
data.tar.gz: 7888edb96143bba2691b486e81368bf3917d20ddd1c6fe66a47b2d7f388fe6b0c3808d01cbeafdcfe2ee7e97bc0e0ab72ab59e20759b049f0ac10cc6ad2d306a
|
data/.gitignore
CHANGED
data/CHANGELOG.md
CHANGED
@@ -5,6 +5,6 @@ All notable changes to this project will be documented in this file.
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
7
7
|
|
8
|
-
## 0.
|
8
|
+
## 0.1.3
|
9
9
|
|
10
10
|
- In the beginning...
|
data/README.md
CHANGED
@@ -1,8 +1,10 @@
|
|
1
|
-
#
|
1
|
+
# rails_respond_to_pb
|
2
2
|
|
3
|
-
|
3
|
+
[![Gem Version](https://badge.fury.io/rb/rails_respond_to_pb.svg)](https://badge.fury.io/rb/rails_respond_to_pb)
|
4
4
|
|
5
|
-
|
5
|
+
This gem allows you to route RPC calls via protobuf to an existing rails controller. Currently supporting:
|
6
|
+
|
7
|
+
- [Twirp](https://github.com/twitchtv/twirp-ruby)
|
6
8
|
|
7
9
|
## Installation
|
8
10
|
|
@@ -14,25 +16,171 @@ gem 'rails_respond_to_pb'
|
|
14
16
|
|
15
17
|
And then execute:
|
16
18
|
|
17
|
-
|
19
|
+
```sh
|
20
|
+
bundle install
|
21
|
+
```
|
18
22
|
|
19
23
|
Or install it yourself as:
|
20
24
|
|
21
|
-
|
25
|
+
```sh
|
26
|
+
gem install rails_respond_to_pb
|
27
|
+
```
|
22
28
|
|
23
29
|
## Usage
|
24
30
|
|
25
|
-
|
31
|
+
This gem loads Rails middleware that routes to services with Controllers as Handlers.
|
32
|
+
|
33
|
+
- assumes a single `ThingsService` per controller
|
34
|
+
- Typical Rails namey-ness conventions are followed here
|
35
|
+
- assumes a `ThingsService` routes to a `ThingsController`
|
36
|
+
- looking into building generating proto files from controllers
|
37
|
+
- loads any `_twirp.rb` files that exist within your app's `lib` directory
|
38
|
+
- allows a controller to `respond_to` the `pb` format
|
39
|
+
- currently you'd respond with a `render plain: ThingResponse.new(id: 1, name: 'Foo').to_proto`
|
40
|
+
- looking into `render pb:`
|
41
|
+
|
42
|
+
Generate a proto like this for each of your controllers (`rpc` methods should match your controller methods. `message` is to your discretion):
|
43
|
+
|
44
|
+
```proto
|
45
|
+
syntax = "proto3";
|
46
|
+
|
47
|
+
service Things {
|
48
|
+
// these rpc methods are important - use what's in the corresponding ThingsController.
|
49
|
+
// whatever is sent as an argument will be made available to the controller as `params`
|
50
|
+
rpc Create (ThingParams) returns (ThingResponse);
|
51
|
+
rpc Show (ThingParams) returns (ThingResponse);
|
52
|
+
rpc Index (ThingFilter) returns (ThingList);
|
53
|
+
rpc Update (ThingParams) returns (ThingResponse);
|
54
|
+
rpc Destroy (ThingParams) returns (ThingResponse);
|
55
|
+
}
|
56
|
+
|
57
|
+
message ThingParams {
|
58
|
+
int32 id = 1;
|
59
|
+
string name = 2;
|
60
|
+
}
|
61
|
+
|
62
|
+
message ThingFilter {
|
63
|
+
string name = 1;
|
64
|
+
}
|
65
|
+
|
66
|
+
message ThingResponse {
|
67
|
+
int32 id = 1;
|
68
|
+
string name = 2;
|
69
|
+
}
|
70
|
+
|
71
|
+
message ThingList {
|
72
|
+
repeated ThingResponse things = 1;
|
73
|
+
}
|
74
|
+
```
|
75
|
+
|
76
|
+
### Server
|
77
|
+
|
78
|
+
This gem will allow your app to respond to Twirp requests. There is little setup required, other than having the prerequisite Service files loaded in your application.
|
79
|
+
|
80
|
+
Given a Service file of `ThingsService`, this gem assumes the presence of a `ThingsController` with actions corresponding with `rpc` methods. To allow your controller to respond to the RPC request, simply update the action accordingly:
|
81
|
+
|
82
|
+
```ruby
|
83
|
+
def index
|
84
|
+
# ... business as usual
|
85
|
+
|
86
|
+
respond_to do |format|
|
87
|
+
format.pb do
|
88
|
+
render plain: ThingList.new(things: Thing.all.map { |r| ThingResponse.new(r.as_json) }).to_proto
|
89
|
+
end
|
90
|
+
format.json { render: Thing.all.as_json } # or whatever your controller responds to usually
|
91
|
+
end
|
92
|
+
end
|
93
|
+
```
|
94
|
+
|
95
|
+
The **required** setup here is:
|
96
|
+
|
97
|
+
```ruby
|
98
|
+
respond_to do |format|
|
99
|
+
format.pb do
|
100
|
+
render plain: YourProtoResponse.to_proto
|
101
|
+
```
|
102
|
+
|
103
|
+
Of note, if you're trying to wire up **entirely new** methods, you do **NOT** need this gem at all, and you can simply add this to your routes file:
|
104
|
+
|
105
|
+
```ruby
|
106
|
+
handler = ThingsHandler.new()
|
107
|
+
service = ThingsService.new(handler)
|
108
|
+
|
109
|
+
mount service, at: service.full_name
|
110
|
+
```
|
111
|
+
|
112
|
+
### Client
|
113
|
+
|
114
|
+
Assuming you have the prerequisite Client files loaded in your application, you can connect to a Twirp server as usual:
|
115
|
+
|
116
|
+
```ruby
|
117
|
+
client = ThingsClient.new('http://localhost:3000')
|
118
|
+
query = ThingFilter.new name: 'foo'
|
119
|
+
client.index(query)
|
120
|
+
```
|
26
121
|
|
27
122
|
## Development
|
28
123
|
|
29
|
-
|
124
|
+
I typically add an alias to make working with dockerized apps easier. This assumes [docker](https://docs.docker.com/get-docker/) is running.
|
30
125
|
|
31
|
-
|
126
|
+
```sh
|
127
|
+
alias dr="docker compose run --rm "
|
128
|
+
```
|
129
|
+
|
130
|
+
After checking out the repo, run `dr bundle install` to spin up a container, and install dependencies. Then, run `dr rspec spec` to run the tests. You can also run `dr bundle console` for an interactive prompt that will allow you to experiment.
|
131
|
+
|
132
|
+
To release a new version, update the version number in `version.rb`, and then run `dr bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
|
133
|
+
|
134
|
+
### Building protos
|
135
|
+
|
136
|
+
For inspiration on how to build proto files locally (and working with docker-compose), here are some services to use within your application:
|
137
|
+
|
138
|
+
```yaml
|
139
|
+
services:
|
140
|
+
bundle: &bundle # run your typical bundle commands
|
141
|
+
env_file: .env
|
142
|
+
stdin_open: true
|
143
|
+
tty: true
|
144
|
+
build: .
|
145
|
+
entrypoint: bundle
|
146
|
+
command: check
|
147
|
+
volumes:
|
148
|
+
- .:/usr/src/app:delegated # hot reload your application's code
|
149
|
+
- bundle:/usr/local/bundle:delegated # cache bundle installs
|
150
|
+
- ~/Projects:/local # used to install gems locally rename ~/Projects to whichever dir your code lives in
|
151
|
+
|
152
|
+
rspec: # run your tests!!
|
153
|
+
<<: *bundle
|
154
|
+
entrypoint: bundle exec rspec
|
155
|
+
command: --version
|
156
|
+
|
157
|
+
protoc: # generate code from proto files
|
158
|
+
build: .
|
159
|
+
entrypoint: bundle
|
160
|
+
command: |
|
161
|
+
exec grpc_tools_ruby_protoc
|
162
|
+
-I ./lib/protos --ruby_out=./lib/protobuf --twirp_ruby_out=./lib/protobuf
|
163
|
+
./lib/protos/things.proto
|
164
|
+
volumes:
|
165
|
+
- .:/usr/src/app:delegated
|
166
|
+
- bundle:/usr/local/bundle:delegated
|
167
|
+
```
|
168
|
+
|
169
|
+
The `twirp_ruby_out` function needs to be made available to your environment. Use a multistage file, like so:
|
170
|
+
|
171
|
+
```dockerfile
|
172
|
+
FROM golang:1 AS go
|
173
|
+
RUN go get github.com/twitchtv/twirp-ruby/protoc-gen-twirp_ruby
|
174
|
+
|
175
|
+
# or whatever version of ruby you're using
|
176
|
+
FROM ruby:3
|
177
|
+
# Install necessary executable to build protos
|
178
|
+
COPY --from=go /go/bin /usr/local/bin
|
179
|
+
```
|
32
180
|
|
33
181
|
## Contributing
|
34
182
|
|
35
|
-
Bug reports and pull requests are welcome on GitHub
|
183
|
+
Bug reports and pull requests are welcome on [GitHub](https://github.com/[USERNAME]/rails_respond_to_pb). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/main/CODE_OF_CONDUCT.md).
|
36
184
|
|
37
185
|
## License
|
38
186
|
|
@@ -40,4 +188,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
|
|
40
188
|
|
41
189
|
## Code of Conduct
|
42
190
|
|
43
|
-
Everyone interacting in the RailsRespondToPb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/
|
191
|
+
Everyone interacting in the RailsRespondToPb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rails_respond_to_pb/blob/main/CODE_OF_CONDUCT.md).
|
data/docker-compose.yml
CHANGED
@@ -9,6 +9,10 @@ services:
|
|
9
9
|
volumes:
|
10
10
|
- .:/usr/src/gem:delegated
|
11
11
|
- bundle:/usr/local/bundle:delegated
|
12
|
+
- ~/.gitconfig:/etc/gitconfig:ro
|
13
|
+
- ~/.ssh:/root/.ssh:ro
|
14
|
+
- ~/.gemrc:/etc/.gemrc:ro
|
15
|
+
- ~/.local/share/gem/credentials:/root/.local/share/gem/credentials:ro
|
12
16
|
|
13
17
|
rspec:
|
14
18
|
<<: *bundle
|
data/rails_respond_to_pb.gemspec
CHANGED
@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
|
|
12
12
|
spec.description = 'Middleware for a Rails App providing functionality for gRPC and Twirp'
|
13
13
|
spec.homepage = 'https://github.com/dudo/rails_respond_to_pb'
|
14
14
|
spec.license = 'MIT'
|
15
|
-
spec.required_ruby_version = Gem::Requirement.new('>=
|
15
|
+
spec.required_ruby_version = Gem::Requirement.new('>= 2.7')
|
16
16
|
|
17
17
|
# spec.metadata['allowed_push_host'] = 'http://mygemserver.com'
|
18
18
|
|
@@ -29,7 +29,9 @@ Gem::Specification.new do |spec|
|
|
29
29
|
spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
|
30
30
|
spec.require_paths = ['lib']
|
31
31
|
|
32
|
+
spec.add_runtime_dependency 'grpc-tools', '~> 1.38'
|
32
33
|
spec.add_runtime_dependency 'rails', ENV['RAILS_VERSION'] || '>= 6'
|
34
|
+
spec.add_runtime_dependency 'twirp', '~> 1.7'
|
33
35
|
|
34
36
|
# For more information and examples about making a new gem, checkout our
|
35
37
|
# guide at: https://bundler.io/guides/creating_gem.html
|
metadata
CHANGED
@@ -1,15 +1,29 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: rails_respond_to_pb
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.1.
|
4
|
+
version: 0.1.4
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Brett C. Dudo
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2021-
|
11
|
+
date: 2021-12-21 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
|
+
- !ruby/object:Gem::Dependency
|
14
|
+
name: grpc-tools
|
15
|
+
requirement: !ruby/object:Gem::Requirement
|
16
|
+
requirements:
|
17
|
+
- - "~>"
|
18
|
+
- !ruby/object:Gem::Version
|
19
|
+
version: '1.38'
|
20
|
+
type: :runtime
|
21
|
+
prerelease: false
|
22
|
+
version_requirements: !ruby/object:Gem::Requirement
|
23
|
+
requirements:
|
24
|
+
- - "~>"
|
25
|
+
- !ruby/object:Gem::Version
|
26
|
+
version: '1.38'
|
13
27
|
- !ruby/object:Gem::Dependency
|
14
28
|
name: rails
|
15
29
|
requirement: !ruby/object:Gem::Requirement
|
@@ -24,6 +38,20 @@ dependencies:
|
|
24
38
|
- - ">="
|
25
39
|
- !ruby/object:Gem::Version
|
26
40
|
version: '6'
|
41
|
+
- !ruby/object:Gem::Dependency
|
42
|
+
name: twirp
|
43
|
+
requirement: !ruby/object:Gem::Requirement
|
44
|
+
requirements:
|
45
|
+
- - "~>"
|
46
|
+
- !ruby/object:Gem::Version
|
47
|
+
version: '1.7'
|
48
|
+
type: :runtime
|
49
|
+
prerelease: false
|
50
|
+
version_requirements: !ruby/object:Gem::Requirement
|
51
|
+
requirements:
|
52
|
+
- - "~>"
|
53
|
+
- !ruby/object:Gem::Version
|
54
|
+
version: '1.7'
|
27
55
|
description: Middleware for a Rails App providing functionality for gRPC and Twirp
|
28
56
|
email:
|
29
57
|
- brett@dudo.io
|
@@ -67,14 +95,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
67
95
|
requirements:
|
68
96
|
- - ">="
|
69
97
|
- !ruby/object:Gem::Version
|
70
|
-
version:
|
98
|
+
version: '2.7'
|
71
99
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
72
100
|
requirements:
|
73
101
|
- - ">="
|
74
102
|
- !ruby/object:Gem::Version
|
75
103
|
version: '0'
|
76
104
|
requirements: []
|
77
|
-
rubygems_version: 3.2.
|
105
|
+
rubygems_version: 3.2.32
|
78
106
|
signing_key:
|
79
107
|
specification_version: 4
|
80
108
|
summary: Middleware for a Rails App providing functionality for gRPC and Twirp
|