gRPC

どのようなものか

gRPCは、遠隔手続き呼び出しのフレームワークです。プログラムは、別のマ
シンで動くサーバーを手元のオブジェクトのように扱い、メソッドを呼びま
す。gRPCが、HTTP/2上の独自プロトコルで呼び出しをネットワーク越しに運
び、応答を戻り値として返します。

出発点はサービス定義です。遠隔で実行する操作と、それぞれのリクエス
ト、応答の型を並べます。既定では、Googleのオープンソースのデータ直列
化形式Protocol
Buffersを使い、末尾が`.proto`のファイルへ書きます。言語やプラット
フォームに依存しない形式です。ほかの形式も組み込めますが、指定しなけ
ればprotocol
buffersを使います。コンパイラー`protoc`とgRPCプラグインがファイルを
読み、両側のコードを生成します。クライアントには、サービスと同じメ
ソッドを持つ手元のオブジェクト、スタブを作ります。単にクライアントと
呼ぶ言語もあります。サーバー側には、実装すべきインターフェースを作り
ます。両側が一ファイルから生まれるため、Java製のサーバーが、Go、
Python、Ruby製のクライアントへ答えられます。

メソッドの形は四つあります。単項メソッドは、普通の関数のように、一つ
のリクエストから一つの応答を返します。サーバーストリーミングは、一つ
のリクエストへ応答のストリームを返し、クライアントストリーミングは、
その逆です。双方向ストリーミングでは、両側が独立してストリームを送れ
ます。一つの呼び出しの中では、送った順でメッセージが届くことをgRPCが
保証します。

通信にはHTTP/2を使います。各呼び出しは、完全修飾したサービス名とメ
ソッド名からなるパスへの`POST`で、コンテンツ型は`application/grpc`で
す。各メッセージの前には五バイトの接頭部があり、一バイトが圧縮の有
無、四バイトが長さを表します。呼び出しの結果は、HTTPの状態ではありま
せん。gRPCが作る応答は、呼び出しが失敗しても状態200で、実際の結果
は、本文の後に送るヘッダーフィールド、トレーラーに入ります。
`grpc-status`が数値を持ち、必要に応じて`grpc-message`がエラーの説明
を持ちます。

このためRESTとは性格が違います。REST
APIは、リソースに名前を付け、HTTP自体のメソッドと状態コードで操作
し、普通は誰でも読めるJSONの本文を使います。gRPC
APIは、型付きのバイナリーメッセージを使うメソッドの一覧で、HTTP/2は
下で運ぶ役目だけです。Protocol
Buffersの文書もJSONと比較し、メッセージの小ささと処理の速さを強調し
ます。

なぜ重要なのか

まず契約があり、そこからコードが生まれます。多くのHTTP
APIでは、APIの説明と、それを実装するコードが別にあり、ずれる場合があ
ります。クライアントも、文書を読んで手で書くことがよくあります。gRPC
では、メソッドやフィールドの定義場所は`.proto`だけで、そこからすべて
のクライアントとサーバーを生成します。メッセージを変えると、誰かが文
書を読み直すのではなく、同じ生成ツールを通して、すべての言語へ伝わり
ます。

コンパクトに符号化できます。各フィールドを、名前ではなく、番号と値で
送るためです。代償として、protocol
buffersは自己記述形式ではないため、`.proto`なしには、完全には解釈で
きません。また、メッセージ全体が一度にメモリーへ収まることを前提とし
ます。公式文書は、数メガバイトを超えるデータには、別の方法を勧めま
す。

ストリーミングは追加機能ではなく、設計の一部です。HTTP/2接続上のスト
リームとして呼び出すため、サーバーストリーミングのメソッドは、一度だ
け答える呼び出しと同じ仕組みで、結果を送り続けられます。

時間制限も呼び出しとともに伝わります。クライアントが期限を設定する
と、gRPCが残り時間を`grpc-timeout`ヘッダーで送り、時間が尽きると、ク
ライアントは`DEADLINE_EXCEEDED`を受け取り、サーバー側の呼び出しは
キャンセルされます。サーバーがさらに別のサーバーを呼ぶとき、一部の実
装は期限を引き継ぎます。JavaとGoは既定で行い、C++は有効化が必要で
す。期限を時刻ではなく残り時間として各区間へ渡すため、時計がずれるマ
シン同士でも、いつ諦めるかは一致します。

エラーにも共通の語彙があります。gRPCは、0の`OK`から16の
`UNAUTHENTICATED`まで、17の状態コードをプロトコル自体に定義します。
そのためGoのクライアントとJavaのサーバーでも、`NOT_FOUND`や
`UNAVAILABLE`の意味が一致します。

どれも、同じチームや企業が両端を管理し、`.proto`を共有してビルドでき
る、サービス間の通信に適しています。ブラウザーには、それほど向きませ
ん。gRPCプロジェクトのプロトコル文書は、ブラウザーはスクリプトへ
HTTP/2のフレーミングを公開しておらず、今後もしないと記します。そのた
めブラウザーのコードは、gRPC-Webという別のプロトコルを使い、普通はプ
ロキシーが通常のgRPCへ変換します。

実際の活用例

小さい請求サービスを示します。一つの単項メソッドが請求書を取得し、一
つのサーバーストリーミングのメソッドが、顧客の請求書を一件ずつ送りま
す。

```protobuf
syntax = "proto3";

package billing.v1;

service InvoiceService {
  rpc GetInvoice(GetInvoiceRequest) returns (Invoice);
  rpc WatchInvoices(WatchInvoicesRequest) returns (stream Invoice);
}

message GetInvoiceRequest {
  string invoice_id = 1;
}

message WatchInvoicesRequest {
  string customer_id = 1;
}

message Invoice {
  reserved 4;
  reserved "discount_code";
  string invoice_id = 1;
  string customer_id = 2;
  int64 total_cents = 3;
  string currency = 5;
}
```

数値は既定値ではありません。フィールド番号で、通信中は名前の代わりに
各フィールドを識別します。1から15は一バイトで符号化できるため、特に
よく設定するフィールドへ割り当てます。二つの`reserved`行は、かつて存
在した、番号4、名前`discount_code`のフィールドを記録し、どちらも別の
フィールドへ使い直せないようにします。

Pythonでは、一つのコマンドが、メッセージのクラスを持つ
`billing_pb2.py`と、クライアントとサーバーのクラスを持つ
`billing_pb2_grpc.py`を生成します。

```sh
python -m grpc_tools.protoc -Iprotos \
  --python_out=. --grpc_python_out=. protos/billing.proto
```

`GetInvoice`の一回の呼び出しは、HTTP/2のフレームでは次のようになりま
す。

```text
HEADERS (flags = END_HEADERS)
i:method = POST		engineer.company	70
i:scheme = https		engineer.company	70
i:path = /billing.v1.InvoiceService/GetInvoice		engineer.company	70
i:authority = billing.example.com		engineer.company	70
te = trailers
content-type = application/grpc+proto
grpc-timeout = 2S

DATA (flags = END_STREAM)
<Length-Prefixed Message>

HEADERS (flags = END_HEADERS)
i:status = 200		engineer.company	70
content-type = application/grpc+proto

DATA
<Length-Prefixed Message>

HEADERS (flags = END_STREAM, END_HEADERS)
grpc-status = 0
```

`2S`は二秒で、`te =
trailers`は、gRPCと互換性のないプロキシーを検出するためです。請求書
がなくても、応答の始まりは`:status =
200`で、最後のフレームに`grpc-status =
5`を入れ、`NOT_FOUND`を表します。`grpc-message`には、例えば
`invoice not
found`を添えます。すぐ失敗するサーバーは、メッセージをまったく付け
ず、状態を入れた一つの`HEADERS`フレームだけを返す場合もあります。

一つの契約から両側を生成するのは、gRPCだけではありません。このサイト
のデータベースを起点にAPI契約を生成した事例は、OpenAPIで記述するAPI
で行いました。流れはデータベースから外へ続きます。Goの型でAPIを定義
し、HumaがOpenAPIの説明を生成し、そこから型付きのTypeScriptクライア
ントとモックハンドラーを作ります。フロントエンドの送るものとAPIの期
待が一致しなくなれば、CIの契約検査がビルドを失敗させます。gRPCは、
`.proto`を唯一のソースにして、同じ規律をツールチェーンへ組み込みま
す。

問題が起きるところ

期限のない呼び出しが、いつまでも待ちます。
gRPCは既定で期限を設定しないため、応答が止まったサーバーを呼ぶクライ
アントは、事実上いつまでも応答を待ち続ける可能性があります。各呼び出
しへ現実的な期限を付けてください。Pythonでは、秒単位の引数`timeout`
です。

```python
import grpc

import billing_pb2
import billing_pb2_grpc

credentials = grpc.ssl_channel_credentials()
with grpc.secure_channel("billing.example.com:443", credentials) as channel:
    stub = billing_pb2_grpc.InvoiceServiceStub(channel)
    request = billing_pb2.GetInvoiceRequest(invoice_id="INV-1001")
    invoice = stub.GetInvoice(request, timeout=2.0)
```

時間が尽きると、`grpc.RpcError`が発生し、その`code()`が
`grpc.StatusCode.DEADLINE_EXCEEDED`を返します。サーバー側では、期限
を過ぎるとgRPCが`CANCELLED`で呼び出しをキャンセルします。ただし、ハ
ンドラーが始めた仕事を止めるのは、サービス自身のコードの責任です。長
く動くハンドラーは、キャンセルを調べ、自分で停止する必要があります。

タイムアウトしても、何も起きなかったとは限りません。
成否はクライアントとサーバーが別々に決めるため、サーバーでは完了して
も、クライアントでは`DEADLINE_EXCEEDED`で失敗する場合があります。
キャンセルしても、済んだ仕事は元へ戻りません。単に再試行すると、同じ
請求書を二度作る可能性があります。冪等であると明示しない限り、プロト
コルはそう仮定しません。`UNAVAILABLE`は、一時的で、待ち時間を置いて
再試行する価値がある可能性の最も高いコードです。ただし状態コードの文
書は、冪等でない操作の再試行は、常に安全とは限らないと警告します。ど
のコードで再試行するかも、呼び出すコードの判断に任せています。

フィールド番号を再利用して、データを壊します。
メッセージ型を使い始めた後は、番号を変えられません。フィールドを消
し、後で番号を別のものへ与えると、古いクライアントや保存したメッセー
ジが、別の意味だったバイト列を、新しいフィールドとしてデコードしま
す。Protocol
Buffersのガイドは、解析エラー、個人データの漏えい、データ破損を挙げ
ます。番号は決して振り直さず、上の例のように、削除した番号と名前をす
べて予約してください。

HTTPからは、どの失敗も成功に見えます。
gRPCは失敗してもHTTP状態200を返すため、アクセスログや状態コードで作
るエラー率など、HTTP状態だけで判断するものは、失敗を成功に数えます。
仕様が、`application/grpc`でないコンテンツ型のリクエストへ415を返さ
せるのも、ほかのHTTP/2クライアントに、gRPCのエラーを成功と読ませない
ためです。`grpc-status`を数え、`:status`で判断しないようにします。

長いストリームが、一台へ負荷を固定します。
呼び出しは共有HTTP/2接続上のストリームで、一度始まると、別のサーバー
へ移せません。何時間も続けば、その後いくらサーバーを増やしても、負荷
は開始した場所に残ります。接続ごとに並行ストリーム数の上限もあり、達
すると、終わるまで後の呼び出しがクライアントで待ちます。gRPCの性能ガ
イドは、性能や単純さの面で大きな利点がある場合だけストリーミングを使
い、負荷の高い領域ごとに、別のチャネルを使うよう勧めます。

大きいデータが、一メッセージに収まりません。
gRPCは最大メッセージサイズを強制し、設定上限を超えると、送信側でも受
信側でも`RESOURCE_EXHAUSTED`で失敗します。上限を上げても、問題が移る
だけです。protocol
buffersは全体がメモリーに収まることを前提とし、大きいデータでは、直
列化したコピーがメモリー内に同時に複数存在する場合があります。小さい
メッセージのストリームへ分けるか、gRPCの外で扱います。

参考資料

  * 基本概念、構成、ライフサイクル — サービス定義、四つのメソッド、
スタブ、期限、キャンセルです。

  * HTTP2上のgRPC — 通信プロトコルで、パス、ヘッダー、メッセージ接頭
部、トレーラーの状態を説明します。

  * 状態コード — 全17コードの意味と、ライブラリー自身が決して作らな
いコードです。

  * 期限 — 既定値がない理由、サーバーへの伝達方法、サービス間の引き
継ぎです。

  * 言語ガイド：proto 3 — フィールド番号、予約フィールド、メッセージ
型を安全に変える規則です。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/grpc/	engineer.company	70
