rails_respond_to_pb
This gem allows you to route RPC calls via protobuf to an existing rails controller. Currently supporting:
Installation
Add this line to your application's Gemfile:
gem 'rails_respond_to_pb'
And then execute:
bundle install
Or install it yourself as:
gem install rails_respond_to_pb
Usage
This gem loads Rails middleware that routes to services with Controllers as Handlers.
- assumes a single
ThingsService
per controller- Typical Rails namey-ness conventions are followed here
- assumes a
ThingsService
routes to aThingsController
- looking into building generating proto files from controllers
- assumes a
- Typical Rails namey-ness conventions are followed here
- loads any
_twirp.rb
files that exist within your app'slib
directory - allows a controller to
respond_to
thepb
format- currently you'd respond with a
render plain: ThingResponse.new(id: 1, name: 'Foo').to_proto
- looking into
render pb:
- looking into
- currently you'd respond with a
Generate a proto like this for each of your controllers (rpc
methods should match your controller methods. message
is to your discretion):
syntax = "proto3";
service Things {
// these rpc methods are important - use what's in the corresponding ThingsController.
// whatever is sent as an argument will be made available to the controller as `params`
rpc Create (ThingParams) returns (ThingResponse);
rpc Show (ThingParams) returns (ThingResponse);
rpc Index (ThingFilter) returns (ThingList);
rpc Update (ThingParams) returns (ThingResponse);
rpc Destroy (ThingParams) returns (ThingResponse);
}
message ThingParams {
int32 id = 1;
string name = 2;
}
message ThingFilter {
string name = 1;
}
message ThingResponse {
int32 id = 1;
string name = 2;
}
message ThingList {
repeated ThingResponse things = 1;
}
Server
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.
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:
def index
# ... business as usual
respond_to do |format|
format.pb do
render plain: ThingList.new(things: Thing.all.map { |r| ThingResponse.new(r.as_json) }).to_proto
end
format.json { render: Thing.all.as_json } # or whatever your controller responds to usually
end
end
The required setup here is:
respond_to do |format|
format.pb do
render plain: YourProtoResponse.to_proto
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:
handler = ThingsHandler.new()
service = ThingsService.new(handler)
mount service, at: service.full_name
Client
Assuming you have the prerequisite Client files loaded in your application, you can connect to a Twirp server as usual:
client = ThingsClient.new('http://localhost:3000')
query = ThingFilter.new name: 'foo'
client.index(query)
Development
I typically add an alias to make working with dockerized apps easier. This assumes docker is running.
alias dr="docker compose run --rm "
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.
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.
Building protos
For inspiration on how to build proto files locally (and working with docker-compose), here are some services to use within your application:
services:
bundle: &bundle # run your typical bundle commands
env_file: .env
stdin_open: true
tty: true
build: .
entrypoint: bundle
command: check
volumes:
- .:/usr/src/app:delegated # hot reload your application's code
- bundle:/usr/local/bundle:delegated # cache bundle installs
- ~/Projects:/local # used to install gems locally rename ~/Projects to whichever dir your code lives in
rspec: # run your tests!!
<<: *bundle
entrypoint: bundle exec rspec
command: --version
protoc: # generate code from proto files
build: .
entrypoint: bundle
command: |
exec grpc_tools_ruby_protoc
-I ./lib/protos --ruby_out=./lib/protobuf --twirp_ruby_out=./lib/protobuf
./lib/protos/things.proto
volumes:
- .:/usr/src/app:delegated
- bundle:/usr/local/bundle:delegated
The twirp_ruby_out
function needs to be made available to your environment. Use a multistage file, like so:
FROM golang:1 AS go
RUN go get github.com/twitchtv/twirp-ruby/protoc-gen-twirp_ruby
# or whatever version of ruby you're using
FROM ruby:3
# Install necessary executable to build protos
COPY --from=go /go/bin /usr/local/bin
Contributing
Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the RailsRespondToPb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.