installation.md

Installation

There are currently three ways to use gRPC Federation.

1. Use buf generate
2. Use protoc-gen-grpc-federation
3. Use grpc-federation-generator

1. Use buf generate

If your project can use Buf, this is the easiest way.
gRPC Federation is already registered with the Buf Registry.

• Schema: https://buf.build/mercari/grpc-federation
• Plugin: https://buf.build/community/mercari-grpc-federation

Therefore, if you installed buf CLI, you can simply run the buf generate command to use gRPC Federation.

Documentation for Buf's code generation is here

Here is a sample of buf.work.yaml and buf.gen.yaml.

• buf.work.yaml

version: v1
directories:
  - proto

• buf.gen.yaml

version: v1
managed:
  enabled: true
plugins:
  - plugin: go
    out: gen
    opt:
      - paths=source_relative
  - plugin: go-grpc
    out: gen
    opt:
      - paths=source_relative
  - plugin: buf.build/community/mercari-grpc-federation:v0.10.0
    out: gen
    opt:
      - paths=source_relative

Also, place buf.yaml under the proto directory.

• proto/buf.yaml

version: v1
deps:
  - buf.build/mercari/grpc-federation
lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

By writing buf.build/mercari/grpc-federation in deps section, it will find the gRPC Federation proto file.

Finally, save the following proto as proto/example.proto and run buf generate to generate the results under gen directory.

• proto/example.proto

syntax = "proto3";

package example.bff;

import "grpc/federation/federation.proto";

option go_package = "example/bff;bff";

service BFF {
  option (grpc.federation.service) = {};
  rpc Get(GetRequest) returns (GetResponse) {};
}

message GetRequest {}
message GetResponse {
  option (grpc.federation.message).custom_resolver = true;
}

2. Use protoc-gen-grpc-federation

2.1. Install protoc-gen-grpc-federation

protoc-gen-grpc-federation is a protoc plugin made by Go. It can be installed with the following command.

go install github.com/mercari/grpc-federation/cmd/protoc-gen-grpc-federation@latest

2.2. Put gRPC Federation proto file to the import path

Copy the gRPC Federation proto file to the import path. gRPC Federation's proto file is here.

Also, gRPC Federation depends on the following proto file. These are located in the proto_deps directory and should be added to the import path if necessary.

• google/rpc/code.proto
• google/rpc/error_details.proto

git clone https://github.com/mercari/grpc-federation.git
cd grpc-federation
cp -r proto /path/to/proto
cp -r proto_deps /path/to/proto_deps

2.3. Use gRPC Federation proto file in your proto file.

• my_federation.proto

syntax = "proto3";

package mypackage;

import "grpc/federation/federation.proto";

2.4. Run protoc command with gRPC Federation plugin

protoc -I/path/to/proto -I/path/to/proto_deps --grpc-federation_out=. ./path/to/my_federation.proto

3. Use grpc-federation-generator

grpc-federation-generator is an standalone generator that allows you to use the gRPC Federation code generation functionality without protoc plugin. Also, the code generated by gRPC Federation depends on the code generated by protoc-gen-go and protoc-gen-go-grpc, so it generates file.pb.go and file_grpc.pb.go files at the same time without that plugins. ( This behavior can be optionally disabled )

grpc-federation-generator also has the ability to monitor changes in proto files and automatically generate them, allowing you to perform automatic generation interactively. Combined with the existing hot-reloader tools, it allows for rapid Go application development. The version of the gRPC Federation proto is the version when grpc-federation-generator is built.

3.1. Install grpc-federation-generator

grpc-federation-generator made by Go. It can be installed with the following command.

go install github.com/mercari/grpc-federation/cmd/grpc-federation-generator@latest

3.2. Write configuration file for grpc-federation-generator

Parameters to be specified when running protoc are described in grpc-federation.yaml

• grpc-federation.yaml

# specify import paths.
imports:
  - proto

# specify the directory where your proto files are located.
# In watch mode, files under these directories are recompiled and regenerated immediately when changes are detected.
src:
  - proto

# specify the destination of gRPC Federation's code-generated output.
out: .

# specify plugin options to be used during code generation of gRPC Federation.
# The format of this plugins section is same as [buf.gen.yaml](https://buf.build/docs/configuration/v1/buf-gen-yaml#plugins).
# Of course, other plugins can be specified, such as `buf.gen.yaml`.
plugins:
  - plugin: go
    opt: paths=source_relative
  - plugin: go-grpc
    opt: paths=source_relative
  - plugin: grpc-federation
    opt: paths=source_relative

3.3. Run grpc-federation-generator

If a proto file is specified, code generation is performed on that file.

grpc-federation-generator ./path/to/my_federation.proto

When invoked with the -w option, it monitors changes to the proto files within the directories specified in grpc-federation.yaml and automatically compiles and generates code.

grpc-federation-generator -w

Note

In the future, we plan to implement a mechanism for code generation by other plugins in combination with buf.work.yaml and buf.gen.yaml definitions.