README
¶
grpc
gRPC 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.
Using gRPC and go-kit together is very simple.
First, define your service using protobuf3. This is explained in gRPC documentation. See 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.
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.
brew install autoconf automake libtool
git clone https://github.com/google/protobuf
cd protobuf
./autogen.sh ; ./configure ; make ; make install
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. See 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 for a complete working example with gRPC support. And remember: go-kit services can support multiple transports simultaneously.
Documentation
¶
Overview ¶
Package grpc provides a gRPC binding for endpoints.
Index ¶
- func EncodeKeyValue(key, val string) (string, string)
- type Client
- type ClientOption
- type ClientRequestFunc
- type ClientResponseFunc
- type DecodeRequestFunc
- type DecodeResponseFunc
- type EncodeRequestFunc
- type EncodeResponseFunc
- type Handler
- type Server
- type ServerOption
- type ServerRequestFunc
- type ServerResponseFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodeKeyValue ¶
EncodeKeyValue sanitizes a key-value pair for use in gRPC metadata headers.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps a gRPC connection and provides a method that implements endpoint.Endpoint.
func NewClient ¶
func NewClient( cc *grpc.ClientConn, serviceName string, method string, enc EncodeRequestFunc, dec DecodeResponseFunc, grpcReply interface{}, options ...ClientOption, ) *Client
NewClient constructs a usable Client for a single remote endpoint. Pass an zero-value protobuf message of the RPC response type as the grpcReply argument.
type ClientOption ¶
type ClientOption func(*Client)
ClientOption sets an optional parameter for clients.
func ClientAfter ¶
func ClientAfter(after ...ClientResponseFunc) ClientOption
ClientAfter sets the ClientResponseFuncs that are applied to the incoming gRPC response prior to it being decoded. This is useful for obtaining response metadata and adding onto the context prior to decoding.
func ClientBefore ¶
func ClientBefore(before ...ClientRequestFunc) ClientOption
ClientBefore sets the RequestFuncs that are applied to the outgoing gRPC request before it's invoked.
type ClientRequestFunc ¶
ClientRequestFunc may take information from context and use it to construct metadata headers to be transported to the server. ClientRequestFuncs are executed after creating the request but prior to sending the gRPC request to the server.
func SetRequestHeader ¶
func SetRequestHeader(key, val string) ClientRequestFunc
SetRequestHeader returns a ClientRequestFunc that sets the specified metadata key-value pair.
type ClientResponseFunc ¶
type ClientResponseFunc func(ctx context.Context, header metadata.MD, trailer metadata.MD) context.Context
ClientResponseFunc may take information from a gRPC metadata header and/or trailer and make the responses available for consumption. ClientResponseFuncs are only executed in clients, after a request has been made, but prior to it being decoded.
type DecodeRequestFunc ¶
DecodeRequestFunc extracts a user-domain request object from a gRPC request. It's designed to be used in gRPC servers, for server-side endpoints. One straightforward DecodeRequestFunc could be something that decodes from the gRPC request message to the concrete request type.
type DecodeResponseFunc ¶
DecodeResponseFunc extracts a user-domain response object from a gRPC response object. It's designed to be used in gRPC clients, for client-side endpoints. One straightforward DecodeResponseFunc could be something that decodes from the gRPC response message to the concrete response type.
type EncodeRequestFunc ¶
EncodeRequestFunc encodes the passed request object into the gRPC request object. It's designed to be used in gRPC clients, for client-side endpoints. One straightforward EncodeRequestFunc could something that encodes the object directly to the gRPC request message.
type EncodeResponseFunc ¶
EncodeResponseFunc encodes the passed response object to the gRPC response message. It's designed to be used in gRPC servers, for server-side endpoints. One straightforward EncodeResponseFunc could be something that encodes the object directly to the gRPC response message.
type Handler ¶
type Handler interface {
ServeGRPC(ctx oldcontext.Context, request interface{}) (oldcontext.Context, interface{}, error)
}
Handler which should be called from the gRPC binding of the service implementation. The incoming request parameter, and returned response parameter, are both gRPC types, not user-domain.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps an endpoint and implements grpc.Handler.
func NewServer ¶
func NewServer( e endpoint.Endpoint, dec DecodeRequestFunc, enc EncodeResponseFunc, options ...ServerOption, ) *Server
NewServer constructs a new server, which implements wraps the provided endpoint and implements the Handler interface. Consumers should write bindings that adapt the concrete gRPC methods from their compiled protobuf definitions to individual handlers. Request and response objects are from the caller business domain, not gRPC request and reply types.
func (Server) ServeGRPC ¶
func (s Server) ServeGRPC(ctx oldcontext.Context, req interface{}) (oldcontext.Context, interface{}, error)
ServeGRPC implements the Handler interface.
type ServerOption ¶
type ServerOption func(*Server)
ServerOption sets an optional parameter for servers.
func ServerAfter ¶
func ServerAfter(after ...ServerResponseFunc) ServerOption
ServerAfter functions are executed on the HTTP response writer after the endpoint is invoked, but before anything is written to the client.
func ServerBefore ¶
func ServerBefore(before ...ServerRequestFunc) ServerOption
ServerBefore functions are executed on the HTTP request object before the request is decoded.
func ServerErrorLogger ¶
func ServerErrorLogger(logger log.Logger) ServerOption
ServerErrorLogger is used to log non-terminal errors. By default, no errors are logged.
type ServerRequestFunc ¶
ServerRequestFunc may take information from the received metadata header and use it to place items in the request scoped context. ServerRequestFuncs are executed prior to invoking the endpoint.
type ServerResponseFunc ¶
type ServerResponseFunc func(ctx context.Context, header *metadata.MD, trailer *metadata.MD) context.Context
ServerResponseFunc may take information from a request context and use it to manipulate the gRPC response metadata headers and trailers. ResponseFuncs are only executed in servers, after invoking the endpoint but prior to writing a response.
func SetResponseHeader ¶
func SetResponseHeader(key, val string) ServerResponseFunc
SetResponseHeader returns a ResponseFunc that sets the specified metadata key-value pair.
func SetResponseTrailer ¶
func SetResponseTrailer(key, val string) ServerResponseFunc
SetResponseTrailer returns a ResponseFunc that sets the specified metadata key-value pair.