TwirpRails

TwirpRails helps to use twirp-ruby gem with rails.

• twirp code generation from .proto file
• handler, rspec and swagger code generation from .proto file
• mount_twirp route helper to mount handlers
• rpc helper to dry your handlers specs
• ability to log twirp calls by Rails logger

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 rpc/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/twirp').get_name(uid: 'starship').data.name
=> "Name of starship"

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
    let(:team) { create(:team) } 
    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.

Log twirp calls

By default, Rails logs only start of POST request. To get a more detailed log of twirp calls use config.log_twirp_calls configuration option (default true).

You can customize log output by pass a proc.

# config/initializers/twirp_rails.rb
config.log_twirp_calls = -> (event) do
  twirp_call_info = {
    duration: event.duration,
    method: event.payload[:env][:rpc_method],
    params: event.payload[:env][:input].to_h
  }

  if (exception = event.payload[:env][:exception])
    twirp_call_info[:exception] = exception
  end

  Rails.logger.info "method=%{method} duration=%{duration}" % twirp_call_info
end

Generate clients

Clients generator calls protoc to generate code from all proto files from rpc_clients directory to lib/twirp_clients (all files auto required on application startup).

Generator runs without options by executing

$ rails g twirp:clients

Configuration

All configuration options (e.g. paths) can be customized via initializer file generated by

$ rails g twirp:init

API acronym

Gem adds inflector acronym API to correct using services with suffix API. API suffix required by prototool linter with uber2 rules. You can disable this inflection by set to false add_api_acronym configuration option.

Swagger generation

Service generator rails g twirp service generates swagger file in public/swagger by default. You can turn it off or customize path in configuration.

Smart service detection

You can use rails g twirp svc if your Svc or SvcAPI service described at company/service/subservice/version/etc/svc_api.proto and you have no other files svc_api.proto.

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.