From b74e3033e84c925461af2bf7d960d5ccec792f57 Mon Sep 17 00:00:00 2001 From: David Sudia Date: Fri, 23 Jun 2017 11:32:31 -0600 Subject: [PATCH 1/3] update grpc readme information about protoc and streams --- transport/grpc/README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/transport/grpc/README.md b/transport/grpc/README.md index 6c35583c8..e9f37b1ca 100644 --- a/transport/grpc/README.md +++ b/transport/grpc/README.md @@ -2,7 +2,10 @@ [gRPC](http://www.grpc.io/) is an excellent, modern IDL and transport for microservices. If you're starting a greenfield project, Go kit strongly recommends gRPC as your default transport. -And using gRPC and Go kit together is very simple. + +One important note is that while gRPC supports streaming requests and replies, go-kit does not. You can still use streams in your service, but their implementation will not be able to take advantage of many go-kit features like middleware. + +Using gRPC and Go kit together is very simple. First, define your service using protobuf3. This is explained [in gRPC documentation](http://www.grpc.io/docs/#defining-a-service). @@ -10,10 +13,12 @@ See [add.proto](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317 Make sure the proto definition matches your service's Go kit (interface) definition. Next, get the protoc compiler. -Unfortunately, this needs to be done from source. -Fortunately, it's pretty straightforward. -``` +You can download pre-compiled binaries from the [protobuf release page](https://github.com/google/protobuf/releases). You will unzip a folder called `protoc3` with a subdirectory `bin` containing an executable. Move that executable somewhere in your `$PATH` and you're good to go! + +It can also be built from source. + +```sh brew install autoconf automake libtool git clone https://github.com/google/protobuf cd protobuf @@ -22,7 +27,7 @@ cd protobuf Then, compile your service definition, from .proto to .go. -``` +```sh protoc add.proto --go_out=plugins=grpc:. ``` From 2855aefe9a9eac9fa69c1f02cabef896579c0c7b Mon Sep 17 00:00:00 2001 From: David Sudia Date: Wed, 12 Jul 2017 19:35:46 -0600 Subject: [PATCH 2/3] style fixes --- transport/grpc/README.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/transport/grpc/README.md b/transport/grpc/README.md index e9f37b1ca..70790e476 100644 --- a/transport/grpc/README.md +++ b/transport/grpc/README.md @@ -1,20 +1,29 @@ # grpc -[gRPC](http://www.grpc.io/) is an excellent, modern IDL and transport for microservices. -If you're starting a greenfield project, Go kit strongly recommends gRPC as your default transport. +[gRPC](http://www.grpc.io/) is an excellent, modern IDL and transport for +microservices. +If you're starting a greenfield project, go-kit strongly recommends gRPC as +your default transport. -One important note is that while gRPC supports streaming requests and replies, go-kit does not. You can still use streams in your service, but their implementation will not be able to take advantage of many go-kit features like middleware. +One important note is that while gRPC supports streaming requests and replies, +go-kit does not. You can still use streams in your service, but their +implementation will not be able to take advantage of many go-kit features like middleware. -Using gRPC and Go kit together is very simple. +Using gRPC and go-kit together is very simple. First, define your service using protobuf3. This is explained [in gRPC documentation](http://www.grpc.io/docs/#defining-a-service). -See [add.proto](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/pb/add.proto) for an example. -Make sure the proto definition matches your service's Go kit (interface) definition. +See +[add.proto](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/pb/add.proto) +for an example. +Make sure the proto definition matches your service's go-kit (interface) definition. Next, get the protoc compiler. -You can download pre-compiled binaries from the [protobuf release page](https://github.com/google/protobuf/releases). You will unzip a folder called `protoc3` with a subdirectory `bin` containing an executable. Move that executable somewhere in your `$PATH` and you're good to go! +You can download pre-compiled binaries from the +[protobuf release page](https://github.com/google/protobuf/releases). +You will unzip a folder called `protoc3` with a subdirectory `bin` containing an executable. +Move that executable somewhere in your `$PATH` and you're good to go! It can also be built from source. @@ -33,10 +42,13 @@ protoc add.proto --go_out=plugins=grpc:. Finally, write a tiny binding from your service definition to the gRPC definition. It's a simple conversion from one domain to another. -See [grpc_binding.go](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/grpc_binding.go) for an example. +See +[grpc_binding.go](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/grpc_binding.go) +for an example. That's it! The gRPC binding can be bound to a listener and serve normal gRPC requests. -And within your service, you can use standard Go kit components and idioms. -See [addsvc](https://github.com/go-kit/kit/tree/master/examples/addsvc) for a complete working example with gRPC support. -And remember: Go kit services can support multiple transports simultaneously. +And within your service, you can use standard go-kit components and idioms. +See [addsvc](https://github.com/go-kit/kit/tree/master/examples/addsvc) for a complete +working example with gRPC support. +And remember: go-kit services can support multiple transports simultaneously. From 9fc967233a085e307b6df65e816bfb78c45189bd Mon Sep 17 00:00:00 2001 From: David Sudia Date: Wed, 12 Jul 2017 19:42:10 -0600 Subject: [PATCH 3/3] made wraps more readable in transport/grpc readme --- transport/grpc/README.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/transport/grpc/README.md b/transport/grpc/README.md index 70790e476..f57dc99fb 100644 --- a/transport/grpc/README.md +++ b/transport/grpc/README.md @@ -1,9 +1,8 @@ # grpc [gRPC](http://www.grpc.io/) is an excellent, modern IDL and transport for -microservices. -If you're starting a greenfield project, go-kit strongly recommends gRPC as -your default transport. +microservices. If you're starting a greenfield project, go-kit strongly +recommends gRPC as your default transport. One important note is that while gRPC supports streaming requests and replies, go-kit does not. You can still use streams in your service, but their @@ -11,19 +10,20 @@ implementation will not be able to take advantage of many go-kit features like m Using gRPC and go-kit together is very simple. -First, define your service using protobuf3. -This is explained [in gRPC documentation](http://www.grpc.io/docs/#defining-a-service). +First, define your service using protobuf3. This is explained +[in gRPC documentation](http://www.grpc.io/docs/#defining-a-service). See [add.proto](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/pb/add.proto) -for an example. -Make sure the proto definition matches your service's go-kit (interface) definition. +for an example. Make sure the proto definition matches your service's go-kit +(interface) definition. Next, get the protoc compiler. You can download pre-compiled binaries from the [protobuf release page](https://github.com/google/protobuf/releases). -You will unzip a folder called `protoc3` with a subdirectory `bin` containing an executable. -Move that executable somewhere in your `$PATH` and you're good to go! +You will unzip a folder called `protoc3` with a subdirectory `bin` containing +an executable. Move that executable somewhere in your `$PATH` and you're good +to go! It can also be built from source. @@ -40,8 +40,8 @@ Then, compile your service definition, from .proto to .go. protoc add.proto --go_out=plugins=grpc:. ``` -Finally, write a tiny binding from your service definition to the gRPC definition. -It's a simple conversion from one domain to another. +Finally, write a tiny binding from your service definition to the gRPC +definition. It's a simple conversion from one domain to another. See [grpc_binding.go](https://github.com/go-kit/kit/blob/ec8b02591ee873433565a1ae9d317353412d1d27/examples/addsvc/grpc_binding.go) for an example. @@ -49,6 +49,6 @@ for an example. That's it! The gRPC binding can be bound to a listener and serve normal gRPC requests. And within your service, you can use standard go-kit components and idioms. -See [addsvc](https://github.com/go-kit/kit/tree/master/examples/addsvc) for a complete -working example with gRPC support. -And remember: go-kit services can support multiple transports simultaneously. +See [addsvc](https://github.com/go-kit/kit/tree/master/examples/addsvc) for +a complete working example with gRPC support. And remember: go-kit services +can support multiple transports simultaneously.