第二部：技術領域への案内
実践: gRPC in Ruby
本章では、gRPC in Ruby の Quick Start から一歩先、「Wantedly で Ruby を使って gRPC Server/Client の開発をどう行なっているのか」について紹介します。
Ruby で gRPC Server を作る
ディレクトリ構成 with Rails
まずはディレクトリ構成について説明します。基本的に Ruby on Rails の上で作ることを想定しています。
1
.
2
├── app
3
│ ├── grpc_services
4
│ ├── models
5
│ └── pb_serializers
6
├── bin
7
├── config
8
└── db
Copied!
特徴的な部分を紹介します。
app/grpc_services- protobuf から生成したサービスクラスを継承したサービスクラスを置きます
- ファイル名およびクラス名にはそれぞれ
_grpc_service,GrpcServiceという suffix を付与します
app/pb_serializers- Protobuf Message object を生成する pb-serializer の実装クラスを配置します
- ファイル名およびクラス名にはそれぞれ
_pb_serializer,PbSerializerという suffix を付与します
wantedly/apis - gRPC のインタフェース定義
apis は Wantedly で .proto file を集約するための repository です。apis へ PR を作るだけで、CI によって「各言語向けのコード生成」が自動で行われるようになっており、「protoc のセットアップ」などの煩雑な作業を個々の開発者がしなくても良い仕組みになっています。
Ruby であれば wantedly/apis-ruby というリポジトリに生成コードがコミットされ、private gem として配信されるようになっています。 各マイクロサービスリポジトリでは、Gemfile に apis を記述した後に bundle install を行って利用するというフローになっています。 以前は apis 内のコードは明示的に require を書かなければ読み込まれなかったのですが、バージョン 2021.12.22.1128 以降から自動的に読み込まれるようになったので、現在では個々の開発者が require を書く必要はありません。
RPC の実装
さて、apis repository によって「gRPC Service Class」と「Protocol Buffers Message Class」のコードを生成して配信することができました。gRPC Server が意味のある response を返すには、これらを利用して ロジックを実装する必要があります。
一例として、
ProfileService の BatchGetProfiles という RPC の処理を見てみましょう。 以下のように、apis で生成された gRPC Service Class である W::UsersPb::ProfileService::Service を継承した ProfileGrpcService Class で、 batch_get_profiles method を実装します。 この例は簡略化して書いてますが、実際にはメソッド内でDB への問い合わせるなどして意味のあるデータを保持したオブジェクトを作成、 最終的に W::UsersPb::BatchGetProfilesResponse オブジェクトとして返します。1
# Protobuf で `wantedly.foo.bar` というパッケージがあったとき、
2
# Ruby では `W::Foo::BarPb` というモジュールとする規約になっている
3
class ProfileGrpcService < W::UsersPb::ProfileService::Service
4
# @param [W::UsersPb::BatchGetProfilesRequest] req
5
# @param [GRPC::ActiveCall::SingleReqView] call
6
# @return [W::UsersPb::BatchGetProfilesResponse]
7
def batch_get_profiles(req, call)
8
# ...
9
10
W::UsersPb::BatchGetProfileResponse.new(profiles: profiles)
11
end
12
end
Copied!
ここで引数に渡ってくる
req はリクエストメッセージで、 call は呼び出しに関する情報を持つ GPRC::ActiveCall^grpc-activecallのオブジェクトです (正確には GRPC::ActiveCall::SingleReqView または GRPC::ActiveCall::MultieReqViewのどちらか)。call.matadata とするとメタデータが取得することができます。the_pb と pb-serializer によるメッセージの組み立て
Ruby では通常は以下のようにして Protobuf object を作ります。
1
message = W::UsersPb::Profile.new(
2
user_id: profile.user_id, # uint64
3
name: profile.name, # string
4
avatar_url: profile.avatar_url, # string
5
)
6
message.to_proto # => binary
Copied!
上記は最も単純な例です。protobufスキーマとgRPC通信で紹介されているラッパー型など、 いわゆる Well-Known Types が入ってくると、もっと面倒なコードを書くことになります（面倒なのでここには書きません）。
the_pb は Ruby オブジェクトを前述した Well-Known Types に変換するユーティリティを提供する gem です。 pb-serializer は ActiveModelSerializers のような DSL で Protobuf object の Serializer を実装できる gem です。内部では the_pb に依存しています。
先程例に出した
Profile object の serializer であれば以下のように実装できます。1
# @attr_reader [::Profile] object
2
class ProfilePbSerializer < Pb::Serializer::Base
3
message W::UsersPb::Profile
4
5
attribute :user_id
6
attribute :name
7
# avatar_url が google.protobuf.StringValue だったとしても、よしなに変換してくれる
8
attribute :avatar_url, allow_nil: true
9
end
10
11
ProfilePbSerializer.new(profile).to_pb
12
# => <W::UsersPb::Profile ...>
Copied!
the_pb と pb-serializer をうまく活用することで、gRPC server 実装時の手間を大きく削減することが出来ます。 pb-serializer の詳しい使い方についてはリポジトリ の README や examples を参照してください。
エラーハンドリング
Ruby における gRPC server の実装では、
GRPC::BadStatus^grpc-badstatus というエラークラスを raise することでクライアントにエラーを返すことになります。 また、エラーコードごとに GRPC::BadStatus のサブクラスが用意されており、それを利用することも出来ます。 以下2行は同じ意味になります。1
raise GRPC::BadStatus, Google::Rpc::Code::NOT_FOUND, "user not found"
2
raise GRPC::NotFound, "user not found"
Copied!
この「エラーコード」は
google.rpc.Code^google-rpc-code に定義されている Protobuf の Enum になります。 エラーコードの使い分けなどについてはprotobufスキーマとgRPC通信を参照してください。複雑なエラー表現
さて、
GRPC::BadStatus と Google::Rpc::Code を利用することでメッセージとエラーコードからなる単純なエラーを表現することは出来ました。 しかし、これでは実際のアプリケーションで表現力が足りません。 例えば単純なフォームのバリデーションエラーでも、フィールドごとにエラーメッセージを保持できる必要があります。1
message Status {
2
// The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
3
int32 code = 1;
4
5
// A developer-facing error message, which should be in English. Any
6
// user-facing error message should be localized and sent in the
7
// [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
8
string message = 2;
9
10
// A list of messages that carry the error details. There is a common set of
11
// message types for APIs to use.
12
repeated google.protobuf.Any details = 3;
13
}
Copied!
この
google.rpc.Status のうち、 Any の配列である details にエラーの詳細を詰めることが可能です。 Google API Design Guide の Errors では google/rpc/error_details.proto に定義されるメッセージの利用が推奨されており、Wantedly でもそれに則っています。Ruby でのエラー詳細の扱いに関しては、the_pb gem で
.new_rpc_error という関数が提供されており、それを使うと便利です。1
raise Pb.new_rpc_error(
2
"post is invalid",
3
code: Google::Rpc::Code::INVALID_ARGUMENT,
4
details: [
5
Google::Rpc::BadRequest.new(
6
field_violations: [{ field: 'title', description: 'タイトルは必須です' }],
7
)
8
],
9
)
Copied!
テスト
gRPC の RPC の実装は見ての通り普通のメソッドなので、最も単純には普通にメソッド呼び出しをして、返り値に対してテストをすることが出来ます。
1
require 'rails_helper'
2
3
RSpec.describe ProfileGrpcService do
4
let(:grpc_service) { described_class.new }
5
let(:call) { instance_double("GRPC::ActiveCall::SingleReqView", metadata: {}) }
6
7
describe '#batch_get_profiles' do
8
let(:request) { W::UsersPb::BatchGetProfilesRequest.new(user_ids: user_ids) }
9
let(:response) { grpc_service.batch_get_profiles(request, call) }
10
let(:user_ids) do
11
# ...
12
end
13
14
it 'returns user profiles' do
15
# ...
16
end
17
end
18
end
Copied!
ただ、これだと Protobuf の marshal / unmarshal 含め gRPC の内部実装を全く介さないため、 もう少し丁寧にやるなら
GrpcTesting module^grpc-testing (private library) の利用を検討するといいでしょう。1
require 'rails_helper'
2
3
RSpec.describe ProfileGrpcService do
4
include GrpcTesting
5
let(:stub) { test_stub_class(described_class.superclass.module_parent).new(described_class.new) }
6
7
describe '#batch_get_profiles' do
8
let(:response) { stub.batch_get_profiles(request, call) }
9
10
# ...
11
end
12
end
Copied!
起動・デバッグ
次に、gRPC Server Process を起動します。gRPC Server を起動して Request を処理させるには、
app/grpc_services に定義した「gRPC Service Class を継承した Class」を Handler として登録する必要があります。また、Wantedly では、マイクロサービスは Kubernetes 上で Docker Container として動かしているので、Heath Check の為に gRPC Health Checking Protocol を実装した Handler の登録も必要です。その他、Observability を高めるための gRPC interceptor（gRPC の拡張機能。後述するが、Rack Middleware 相当のもの）の設定なども行う必要があります。こういった「どの repository でも共通で必要になる処理」については、個々の開発者が気にする必要がないよう、servicex (internal) と呼ばれる社内 library (gem) の機能として提供するようにしています。具体的には、grpc-server という名前のコマンドを用意しており、それを実行するだけで「gRPC Service Class の load および Handler としての登録、その他に共通で必要になる各種設定」が行われるようにしています。
grpc-server コマンドは以下のように利用することができます。1
$ bundle exec grpc-server
2
handling /grpc.health.v1.Health/Check with #<Method: Grpc::Health::Checker#check>
3
handling /grpc.health.v1.Health/Watch with #<Method: Grpc::Health::Checker(Grpc::Health::V1::Health::Service)#watch>
4
handling /wantedly.users.UserService/ListUsers with #<Method: UsersGrpcService#list_users>
5
.
6
.
7
.
8
gRPC server starting...
9
* Listening on tcp://0.0.0.0:6046
10
* Environment: development
11
Use Ctrl-C to stop
Copied!
gRPC server にリクエストを送ってデバッグする
JSON/HTTP な API であれば cURL コマンドや Insomnia, Postman といったツールで実際にリクエストを送ってデバッグすることがあるかもしれません。 gRPC server では標準でコマンドラインツールが提供されている ほか、grpcurl や evans といった 3rd party のツールが存在します。 一方でこれらのツールでは「元になった .proto ファイル」もしくは「Server Reflection に対応した gRPC server」が必要になり、Wantedly の環境では少し使いづらいという問題がありました。
そこで Wantedly では giro というツールを利用し、なるべく少ない手順・依存で gRPC server にリクエストを送れるような環境になっています。詳しくは giro の解説をしているブログ もしくは giro の使い方ドキュメント (internal) を参照してください。
Ruby で gRPC Client を使う
gRPC Client を開発する際にも、gRPC Server 開発と同様に .proto file を集約する apis repository や servicex と呼ばれる社内 library (gem) を活用するようにしています。
gRPC Client としては、apis repository で自動生成した gRPC Service Class のコードを load したうえで、その Stub Class を利用します。gRPC Client を単純に利用するだけであれば、以下のコードで動きます。
1
client = W::UsersPb::ProfileService::Stub.new(url, :this_channel_is_insecure)
Copied!
ただし、Production の Microservices で利用する上では「必ずセットして欲しい gRPC interceptor（gRPC の拡張機能。後述するが、Faraday Middleware 相当のもの）」などが存在するので、個々の開発者が意識しなくてもそれらの設定が自動で行われる様に、servicex gem の中で
.stub_for という「gRPC Client 生成用のメソッド」を用意しています。1
client = Servicex::Grpc.stub_for(W::UsersPb::ProfileService, grpc_url)
Copied!
.stub_for の実装はだいたい以下のようになっています。 元々、HTTP/1.1 の通信では servicex gem の中で Faraday Middleware などの設定を行なった API Client を提供する様にしていました。 .stub_for は同様の体験を gRPC でも提供することが意図されています。 Observability を確保するための interceptor のセットや User Agent の設定なども .stub_for で自動で行われるようになっています。1
# @example
2
# Servicex::Grpc.stub_for(W::UsersPb::ProfileService, UsersApi.base_url)
3
# @param service_class [Class<Grpc::GeneralService>]
4
# @param url [String]
5
# @yield [opts] To modify options for instantiating a Stub
6
# @yieldparam opts [Hash] Default options
7
def stub_for(service_class, url)
8
opts = {
9
channel_args: {
10
'grpc.primary_user_agent' => Servicex.user_agent,
11
},
12
interceptors: Servicex::Grpc.client_interceptors,
13
}
14
yield opts if block_given?
15
service_class::Stub.new(url, :this_channel_is_insecure, opts)
16
end
Copied!
gRPC Client については、基本的にやる事はこれだけです。 「apis と servicex を gem として load すれば、どのマイクロサービスからでも簡単に必要な設定が行われた状態で gRPC での通信が出来る」という環境を作っています。
最終的にはだいたい以下のようなコードを書くことになります（次節で説明するエラーハンドリングをしない場合のパターンです）。
1
client = Servicex::Grpc.stub_for(
2
W::Users::ProfileService,
3
UsersGrpcApi.base_url, # servicex が提供する、ほかのマイクロサービスの URL を取得する関数
4
current_user_id: current_user.id,
5
)
6
req = W::Users::BatchGetProfileRequest.new(user_ids: user_ids)
7
8
data = client.batch_get_profiles(req)
9
data # => <UsersPb::BatchGetProfilesResponse: profiles: [...]>
Copied!
gRPC Client のエラーハンドリング
gRPC における通信の失敗は gRPC のエラーコードとして表されます。 (Handbook - gRPC 通信のエラーハンドリング にその種類と、デフォルトで考慮すべきものがどれかの指針が書かれているので、確認しておいてください。)
マイクロサービス・アーキテクチャでの開発を行う際には、障害の分離のために、通信の失敗について考慮する必要があります。 通信が失敗した際、全体を失敗させるのではなくなんらか部分的に処理が継続可能な場合は、メソッド呼び出しで errors に想定しているエラーの種類を列挙してください。
これは、
1
client = Servicex::Grpc.stub_for(
2
W::Users::ProfileService,
3
UsersGrpcApi.base_url,
4
current_user_id: current_user.id,
5
)
6
req = W::Users::BatchGetProfileRequest.new(user_ids: user_ids)
7
8
res = client.batch_get_profiles(req, errors: [:deadline_exceeded])
Copied!
これは、GRPC のエラーの種類に対応するシンボルとして指定できます。例えば、GRPC のエラーである DEADLINE_EXCEEDED に対応するシンボルは
:deadline_exceeded です。 また、サーバー側に原因があると考えられる UNKNOWN, INTERNAL, UNAVAILABLE を :server_errors でまとめて指定できるようにしています。多くのケースでは、
errors: [:server_error, :deadline_exceeded] を書くことをまず考えるのが良いプラクティスでしょう。コードレビューの際にも、そのことをチェックしてください。errors を指定すると成功と失敗を表現するオブジェクトが返ってくるので、パターンマッチで処理しましょう。
1
res = client.batch_get_profiles(req, errors: [:server_errors, :deadline_exceeded])
2
case resp
3
in Result::Success(data)
4
data # => <UsersPb::BatchGetProfilesResponse: profiles: [...]>
5
in Result::Failure(error)
6
# Failure の場合は自動で Honeybadger に送られます。
7
error # => [<W::Users::ProfileServiceError: ...>]
8
end
Copied!
エラーの種類によって個別の処理をしたい場合は、こういう風にパターンマッチを書くと良いでしょう。
1
res = client.update_profile(req, errors: [:server_errors, :deadline_exceeded, :permission_denied])
2
case resp
3
in Result::Success(data)
4
data
5
in Result::Failure(type: :permission_denied, error: _error)
6
Pb::Visit::ToastError.new(message: "このデータを更新する権限がありません")
7
in Result::Failure(_error)
8
Pb::Visit::ToastError.new(message: "更新が行なえませんでした。しばらくしてからもう一度やり直してください。")
9
end
Copied!
gRPC Client のモック
1
before do
2
GrpcMock.stub_request('/wantedly.users.ProfileService/BatchGetProfiles').to_return do |req, call|
3
W::UsersPb::BatchGetProfilesResponse.new(
4
profiles: [],
5
)
6
end
7
end
Copied!
ライブラリ・ツールの紹介
Ruby で gRPC を利用するときに利用する内製の gem やツールの一覧です。 pb-serializer や giro のように直接的に利用するものもあれば、servicex 内で利用されているものもあります。
- Ruby で Protocol Buffers を扱う際に便利なユーティリティを集めた gem
- ActiveModelSerializer ライクな DSL で Ruby オブジェクトを Protobuf に変換することができる
- pb-serializer と組み合わせることで、データソースを抽象化したデータの読み込みや GraphQL ライクな field selector が実装できる
- Observability を支える interceptor たち
- gRPC server 開発で Rails のような hot-reloading を実現する
- RPC が返しているオブジェクトが正しい Protobuf messaage かどうかを検証する interceptor
- gRPC server を起動するためのボイラプレートを隠蔽した gem
- 簡単に gRPC server を叩ける CLI
話を聞きに行きたい
もっと知りたい
最終更新 5mo ago