TL;DR
Buf が提供する、Protocol Buffers の API をホスティングする SaaS。proto ファイルの集まりをモジュールとして管理し、公開や配布ができる。
なぜ必要か
モジュールを公開すると、BSR が各言語の SDK を生成する。そのため、利用者は自分でクライアントのコードを生成しなくてよい。Go なら go get、JavaScript や TypeScript なら npm install で、生成されたコードを使える。
仕組み
BSR には、SDK の生成のほかに次の機能がある。
- API ドキュメントを自動で生成する
- API の変更がクライアントに影響しないよう、ポリシーチェックを強制する
- 公開されたモジュールは誰でも使える。たとえば Google の API は
googleapis/googleapisとして公開されている - Buf CLI の buf generate で使う Remote plugins も、BSR で管理されている
例
アカウントを作り、Buf CLI でログインする。認証に成功すると、認証情報が $HOME/.netrc に保存される。
$ buf registry loginBSR の画面でリポジトリを作ったあと、buf push でモジュールを Push する。
$ buf push生成された SDK は、Go なら go get で取り込める。npm では、先に Buf のレジストリを登録してからインストールする。
$ go get buf.build/gen/go/<ユーザ>/<モジュール>/connectrpc/go@latest
$ npm config set @buf:registry https://buf.build/gen/npm/v1/この SDK を使って Connect のサーバとクライアントを実装すると、proto ファイルを手元に置かずに開発できる。Connect で作ったサーバは、Connect、gRPC、gRPC Web のどれでも呼べる。ブラウザから呼ぶときは CORS の設定が必要になる。
注意点
GitHub Actions などの CI 環境で BSR を操作するときは、.netrc ではなく環境変数で認証情報を渡すことが推奨されている。