TwirpRails

TwirpRails helps to use twirp-ruby gem with rails and to automate code generation from .proto files.

Installation

Add this line to your application's Gemfile:

gem 'twirp_rails'

See the twirp-ruby code generation documentation to install required protoc and twirp-ruby plugin.

Usage

Generator

Create a proto file app/protos/people.proto:

syntax = "proto3";

service People {
    rpc getName(GetNameRequest) returns (GetNameResponse);
}

message GetNameRequest {
    string uid = 1;
}

message GetNameResponse {
    string name = 1;
}

and run

rails g twirp people
rails g twirp:rspec # run only once, if you want to use rspec rpc helper

This command will add the route and generate lib/twirp/people_pb.rb, lib/twirp/people_twirp.rb,
public/swagger/people.swagger.json, app/rpc/people_handler.rb and spec/rpc/people_handler_sprc.rb.

# app/rpc/people_handler.rb

class PeopleHandler

  def get_name(req, _env)
    GetNameResponse.new
  end
end

Call RPC

Modify app/rpc/people_handler.rb:

  def get_name(req, _env)
    { name: "Name of #{req.uid}" }
  end

Run rails server

rails s

And check it from rails console.

PeopleClient.new('http://localhost:3000').get_name(GetNameRequest.new uid: '1').data.name
=> "Name of 1"

Test your service with rspec

If you use RSpec, twirp generator creates handler spec file with all service methods test templates.

describe TeamsHandler do

  context '#get' do
    rpc { [:get, id: team.id] }

    it { should match(team: team.to_twirp) }
  end
end

To include required spec helpers add this code to rails_helper.rb

require 'twirp_rails/rspec/helper'

RSpec.configure do |config|
  config.include RSpec::Rails::RequestExampleGroup, type: :request, file_path: %r{spec/api}
end 

or run rails g twirp:rspec to do it automatically.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/severgroup-tt/twirp_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant 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 TwirpRails project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.