vendor/github.com/go-kit/kit/transport/grpc/README.md

   1 # grpc
   2
   3 [gRPC](http://www.grpc.io/) is an excellent, modern IDL and transport for
   4 microservices. If you're starting a greenfield project, go-kit strongly
   5 recommends gRPC as your default transport.
   6
   7 One important note is that while gRPC supports streaming requests and replies,
   8 go-kit does not. You can still use streams in your service, but their
   9 implementation will not be able to take advantage of many go-kit features like middleware.
  10
  11 Using gRPC and go-kit together is very simple.
  12
  13 First, define your service using protobuf3. This is explained
  14 [in gRPC documentation](http://www.grpc.io/docs/#defining-a-service).
  15 See
  16 [add.proto](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/pb/add.proto)
  17 for an example. Make sure the proto definition matches your service's go-kit
  18 (interface) definition.
  19
  20 Next, get the protoc compiler.
  21
  22 You can download pre-compiled binaries from the
  23 [protobuf release page](https://github.com/google/protobuf/releases).
  24 You will unzip a folder called `protoc3` with a subdirectory `bin` containing
  25 an executable. Move that executable somewhere in your `$PATH` and you're good
  26 to go!
  27
  28 It can also be built from source.
  29
  30 ```sh
  31 brew install autoconf automake libtool
  32 git clone https://github.com/google/protobuf
  33 cd protobuf
  34 ./autogen.sh ; ./configure ; make ; make install
  35 ```
  36
  37 Then, compile your service definition, from .proto to .go.
  38
  39 ```sh
  40 protoc add.proto --go_out=plugins=grpc:.
  41 ```
  42
  43 Finally, write a tiny binding from your service definition to the gRPC
  44 definition. It's a simple conversion from one domain to another.
  45 See
  46 [grpc_binding.go](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/grpc_binding.go)
  47 for an example.
  48
  49 That's it!
  50 The gRPC binding can be bound to a listener and serve normal gRPC requests.
  51 And within your service, you can use standard go-kit components and idioms.
  52 See [addsvc](https://github.com/go-kit/kit/tree/master/examples/addsvc) for
  53 a complete working example with gRPC support. And remember: go-kit services
  54 can support multiple transports simultaneously.