gRPC の CUI のクライアントツールを調べてまとめてみた

こんにちは、松浦です。

最近業務にて gRPC を使ったアプリケーションの開発をしています。開発をしていて少し困るのは、動作確認を行うのにどうやって gRPC サーバの RPC メソッドを呼び出すか、という点です。REST のエンドポイントの場合、curl やブラウザや Postman のようなアプリケーションでリクエストを送れましたが、gRPC の場合は、新たなツールを導入する（あるいは、クライアント側のテスト用コードを書く）ことになります。そこで、業務の効率化も兼ねて、お手軽に動作確認を行うのにどのようなクライアントツールがあるのか、調べて、触って、まとめてみることにしました。

前提

本記事では CUI のツールのみを取り上げます（GUI ツールもいくつかありますが、記事の分量と余力の問題で今回は取り上げません……）。
動作確認を行った環境は Mac (OS X 10.14.4) です。
動作確認用の gRPC サーバは 50051 番ポートを使用しています。

動作確認用のサンプルの Protocol Buffers の定義は以下の通りです。

syntax = "proto3";

package sample;

service SampleService {
    // SampleResponse の message には "Hello, ${SampleRequest.name}!" がセットされる
    rpc GetSample(SampleRequest) returns (SampleResponse);
}

message SampleRequest {
    string name = 1;
}

message SampleResponse {
    string message = 1;
}

syntax = "proto3";

package sample;

service SampleService {

// SampleResponse の message には "Hello, ${SampleRequest.name}!" がセットされる

rpc GetSample(SampleRequest) returns (SampleResponse);

}

message SampleRequest {

string name = 1;

}

message SampleResponse {

string message = 1;

}

gRPC command line tool

gRPC command line tool は、gRPC のリポジトリ内にある CLI です。
ソースコードからビルドする必要があるため、インストールは少々手間がかかるのですが、It is desirable to have command line tools written in other languages roughly follow the same syntax and flags. とあるように、gRPC の CLI ツールの望ましいシンタックスやフラグが定義されていると言えるので、勉強として触ってみるのにも良いと思います。

動作確認したバージョン

1.23.0

インストール

ドキュメントの記述に従ってインストールしていきます。
まず、 gRPC のリポジトリを clone します。CLI ツールをビルドするにはサブモジュールをアップデートしておく必要があるので、それも行います。

git clone https://github.com/grpc/grpc
git submodule update --init

1 2	git clone https://github.com/grpc/grpc git submodule update --init

ビルドには gflags のライブラリが必要なのでインストールしておきます。

brew install gflags

1	brew install gflags

ここまでで事前準備は完了なので、CLI をビルドします。

make grpc_cli

1	make grpc_cli

使い方

使い方は grpc_cli help や grpc_cli <command> help で確認できます。
いくつかコマンドがありますが、RPC メソッドを呼び出すには grpc_cli call のコマンドを使用します。

# grpc_cli call <address> [<service>.]<method> <request> <options>
# サーバアプリがリフレクションに対応している場合は proto ファイルの指定は不要
# method の前の service 名は省略できるらしい
$ grpc_cli call 127.0.0.1:50051 GetSample "name: 'TECHSCORE'"
connecting to 127.0.0.1:50051
message: "Hello, TECHSCORE!"

Rpc succeeded with OK status

# grpc_cli call <address> [<service>.]<method> <request> <options>

# サーバアプリがリフレクションに対応している場合は proto ファイルの指定は不要

# method の前の service 名は省略できるらしい

$ grpc_cli call 127.0.0.1:50051 GetSample "name: 'TECHSCORE'"

connecting to 127.0.0.1:50051

message: "Hello, TECHSCORE!"

Rpc succeeded with OK status

gRPCurl

Like cURL, but for gRPC とあるように、gRPC 版 curl と言えるツールです。
GitHub のスターも執筆時点で 2000 を超えており、他の記事でもしばしば言及が見られるので、定評のあるツールと言っていいと思います。

動作確認したバージョン

1.3.2

インストール

Mac の場合は brew でインストールすることができます。
GitHub の releases のページにバイナリもアップロードされているので、そちらを直接取得することもできます。
go get でソース取得・ビルドすることも可能です。

使い方

使い方は grpcurl -help で確認できます。
RPC メソッドを呼び出すには、以下のように各種引数を渡していくことになります。

# grpcurl <options> <address> <fully-qualified service name>/<method>
# no TLS の場合は -plaintext オプションを明示的に付与する
# -d でメッセージの中身を指定(JSON で記述)
# サーバアプリがリフレクションに対応している場合は proto ファイルの指定は不要
$ grpcurl -plaintext -d '{"name": "TECHSCORE"}' 127.0.0.1:50051 sample.SampleService/GetSample
{
  "message": "Hello, TECHSCORE!"
}

# grpcurl <options> <address> <fully-qualified service name>/<method>

# no TLS の場合は -plaintext オプションを明示的に付与する

# -d でメッセージの中身を指定(JSON で記述)

# サーバアプリがリフレクションに対応している場合は proto ファイルの指定は不要

$ grpcurl -plaintext -d '{"name": "TECHSCORE"}' 127.0.0.1:50051 sample.SampleService/GetSample

{

"message": "Hello, TECHSCORE!"

}

余談ですが、ソースコードを読む限り、Prototool の grpc コマンドは内部的には grpcurl を利用しているようです。

grpcc

gRPC 関連のツールは Golang で書かれているものが多い印象がありますが、grpcc は JavaScript (Node.js) で書かれています。
他のツールと比べると少し癖が強いですが、面白いツールだと思います。

動作確認したバージョン

1.1.3

インストール

README にあるように、npm でインストールします。

使い方

使い方は　grpcc -h または grpcc --help で確認できます。
以下は、対話モードで RPC メソッドを呼び出すサンプルです。

# grpcc <options>
# リフレクションには対応していないようなので、 --proto で指定する必要がある
# --address でサーバ側のアドレスを指定
# Insecure な接続の場合は -i オプションを明示的に付与する
$ grpcc --proto Sample.proto --address 127.0.0.1:50051 -i

Connecting to sample.SampleService on 127.0.0.1:50051. Available globals:

  client - the client connection to SampleService
    getSample (SampleRequest, callback) returns SampleResponse

  printReply - function to easily print a unary call reply (alias: pr)
  streamReply - function to easily print stream call replies (alias: sr)
  createMetadata - convert JS objects into grpc metadata instances (alias: cm)
  printMetadata - function to easily print a unary call's metadata (alias: pm)

SampleService@127.0.0.1:50051> client.getSample({name: "TECHSCORE"}, printReply)
EventEmitter {}
SampleService@127.0.0.1:50051>
{
  "message": "Hello, TECHSCORE!"
}

# grpcc <options>

# リフレクションには対応していないようなので、 --proto で指定する必要がある

# --address でサーバ側のアドレスを指定

# Insecure な接続の場合は -i オプションを明示的に付与する

$ grpcc --proto Sample.proto --address 127.0.0.1:50051 -i

Connecting to sample.SampleService on 127.0.0.1:50051. Available globals:

client - the client connection to SampleService

getSample (SampleRequest, callback) returns SampleResponse

printReply - function to easily print a unary call reply (alias: pr)

streamReply - function to easily print stream call replies (alias: sr)

createMetadata - convert JS objects into grpc metadata instances (alias: cm)

printMetadata - function to easily print a unary call's metadata (alias: pm)

SampleService@127.0.0.1:50051> client.getSample({name: "TECHSCORE"}, printReply)

EventEmitter {}

SampleService@127.0.0.1:50051>

{

"message": "Hello, TECHSCORE!"

}

対話モードの他にも、コマンドライン上に書いた JavaScript のコードを実行して結果を出力する --eval オプションや、JavaScript のファイルを実行して結果を出力する --exec オプションなどもあります。

# --eval オプションのサンプル
$ grpcc --proto Sample.proto --address 127.0.0.1:50051 -i --eval 'client.getSample({name: "TECHSCORE"}, printReply)'
{
  "message": "Hello, TECHSCORE!"
}

# --eval オプションのサンプル

$ grpcc --proto Sample.proto --address 127.0.0.1:50051 -i --eval 'client.getSample({name: "TECHSCORE"}, printReply)'

{

"message": "Hello, TECHSCORE!"

}

evans

more expressive universal gRPC client と銘打っているように、かなり高機能で使いやすいツールです。
ちなみに、私が普段使っているツールです。

動作確認したバージョン

0.8.2

インストール

Mac の場合は brew でインストールすることができます。
GitHub の releases ページにバイナリもアップロードされているので、そちらを直接取得することもできます。
go get でソース取得・ビルドすることも可能ですが推奨されていません。

使い方

使い方は evans -h または evans --help で確認できます。
以下は、対話モードで RPC メソッドを呼び出すサンプルです。

# evans <options> <proto file>
# サーバアプリがリフレクションに対応している場合、-r または --reflection で有効化できる（その場合、proto ファイルの指定は不要）
# --package でパッケージ名、--service でサービス名、--call でメソッド名を指定できるが、対話モードの中でも指定が可能
# --host でホスト名、--port でポート名が指定できる（デフォルト値はそれぞれ 127.0.0.1, 50051）
$ evans -r

  ______
 |  ____|
 | |__    __   __   __ _   _ __    ___
 |  __|   \ \ / /  / _. | | '_ \  / __|
 | |____   \ V /  | (_| | | | | | \__ \
 |______|   \_/    \__,_| |_| |_| |___/

 more expressive universal gRPC client


127.0.0.1:50051> package sample

sample@127.0.0.1:50051> service SampleService

sample.SampleService@127.0.0.1:50051> call GetSample
name (TYPE_STRING) => TECHSCORE
{
  "message": "Hello, TECHSCORE!"
}

# evans <options> <proto file>

# サーバアプリがリフレクションに対応している場合、-r または --reflection で有効化できる（その場合、proto ファイルの指定は不要）

# --package でパッケージ名、--service でサービス名、--call でメソッド名を指定できるが、対話モードの中でも指定が可能

# --host でホスト名、--port でポート名が指定できる（デフォルト値はそれぞれ 127.0.0.1, 50051）

$ evans -r

______

| ____|

| |__ __ __ __ _ _ __ ___

| __| \ \ / / / _. | | '_ \ / __|

| |____ \ V / | (_| | | | | | \__ \

|______| \_/ \__,_| |_| |_| |___/

more expressive universal gRPC client

127.0.0.1:50051> package sample

sample@127.0.0.1:50051> service SampleService

sample.SampleService@127.0.0.1:50051> call GetSample

name (TYPE_STRING) => TECHSCORE

{

"message": "Hello, TECHSCORE!"

}

対話モードだけでなく、コマンドライン上で RPC メソッドを呼び出すこともできます。

# メッセージの中身は JSON で記述
$ echo '{"name": "TECHSCORE"}' | evans -r --package sample --service SampleService --call GetSample
{
  "message": "Hello, TECHSCORE!"
}

# メッセージの中身は JSON で記述

$ echo '{"name": "TECHSCORE"}' | evans -r --package sample --service SampleService --call GetSample

{

"message": "Hello, TECHSCORE!"

}

Polyglot

最後に、Java 版クライアントツールの polyglot を見てみます。
README を見ていると、かなり詳細な設定もできそうですが、今回は軽く見るにとどめます。

動作確認したバージョン

2.0.0

インストール

All you need to run Polyglot is a Java runtime. と README の Requirements で言っているので、Java が実行できる環境で、GitHub の releases ページにある Jar をダウンロードする形になります。

使い方

使い方は java -jar polyglot.jar --help で確認できます。
以下では call コマンドを使って RPC メソッドを呼び出すサンプルです。

# java -jar polyglot.jar <options> call <command specific options>
# --endpoint でエンドポイントを、--full_method で呼び出すメソッドを指定する（必須）
# サーバアプリがリフレクションに対応している場合、proto ファイルの指定は不要
# メッセージの中身は JSON で標準入力から受け取る
$ echo '{"name": "TECHSCORE"}' | java -jar polyglot.jar call --endpoint 127.0.0.1:50051 --full_method sample.SampleService/GetSample
[main] INFO me.dinowernli.grpc.polyglot.Main - Polyglot version: 2.0.0
[main] INFO me.dinowernli.grpc.polyglot.Main - Loaded configuration: 
[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Creating channel to: 127.0.0.1:50051
[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Using proto descriptors fetched by reflection
[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Creating dynamic grpc client
[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Making rpc with 1 request(s) to endpoint [127.0.0.1:50051]
[main] INFO me.dinowernli.grpc.polyglot.grpc.DynamicGrpcClient - Making unary call
[grpc-default-executor-1] INFO me.dinowernli.grpc.polyglot.io.LoggingStatsWriter - Got response message
{
  "message": "Hello, TECHSCORE!"
}

[grpc-default-executor-1] INFO me.dinowernli.grpc.polyglot.io.LoggingStatsWriter - Completed rpc with 1 response(s)

# java -jar polyglot.jar <options> call <command specific options>

# --endpoint でエンドポイントを、--full_method で呼び出すメソッドを指定する（必須）

# サーバアプリがリフレクションに対応している場合、proto ファイルの指定は不要

# メッセージの中身は JSON で標準入力から受け取る

$ echo '{"name": "TECHSCORE"}' | java -jar polyglot.jar call --endpoint 127.0.0.1:50051 --full_method sample.SampleService/GetSample

[main] INFO me.dinowernli.grpc.polyglot.Main - Polyglot version: 2.0.0

[main] INFO me.dinowernli.grpc.polyglot.Main - Loaded configuration:

[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Creating channel to: 127.0.0.1:50051

[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Using proto descriptors fetched by reflection

[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Creating dynamic grpc client

[main] INFO me.dinowernli.grpc.polyglot.command.ServiceCall - Making rpc with 1 request(s) to endpoint [127.0.0.1:50051]

[main] INFO me.dinowernli.grpc.polyglot.grpc.DynamicGrpcClient - Making unary call

[grpc-default-executor-1] INFO me.dinowernli.grpc.polyglot.io.LoggingStatsWriter - Got response message

{

"message": "Hello, TECHSCORE!"

}

[grpc-default-executor-1] INFO me.dinowernli.grpc.polyglot.io.LoggingStatsWriter - Completed rpc with 1 response(s)

まとめ

以上、gRPC の CUI のクライアントツールを調べてみました。
調べている過程で GUI のクライアントツールもいくつか面白そうなものを見つけたので、いずれまとめてみたいところです。