grpc

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. And 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. Unfortunately, this needs to be done from source. Fortunately, it's pretty straightforward.

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 BadRequestError
  • func (err BadRequestError) Error() string
• type Client
  • func NewClient(cc *grpc.ClientConn, serviceName string, method string, enc EncodeRequestFunc, ...) *Client
  • func (c Client) Endpoint() endpoint.Endpoint
• type ClientOption
  • func ClientBefore(before ...RequestFunc) ClientOption
• type DecodeRequestFunc
• type DecodeResponseFunc
• type EncodeRequestFunc
• type EncodeResponseFunc
• type Handler
• type RequestFunc
  • func SetRequestHeader(key, val string) RequestFunc
• type ResponseFunc
  • func SetResponseHeader(key, val string) ResponseFunc
• type Server
  • func NewServer(ctx context.Context, e endpoint.Endpoint, dec DecodeRequestFunc, ...) *Server
  • func (s Server) ServeGRPC(grpcCtx context.Context, req interface{}) (context.Context, interface{}, error)
• type ServerOption
  • func ServerAfter(after ...ResponseFunc) ServerOption
  • func ServerBefore(before ...RequestFunc) ServerOption
  • func ServerErrorLogger(logger log.Logger) ServerOption

Functions

func EncodeKeyValue

func EncodeKeyValue(key, val string) (string, string)

EncodeKeyValue sanitizes a key-value pair for use in gRPC metadata headers.

Types

type BadRequestError

type BadRequestError struct {
	Err error
}

BadRequestError is an error in decoding the request.

func (BadRequestError) Error

func (err BadRequestError) Error() string

Error implements the error interface.

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.

func (Client) Endpoint

func (c Client) Endpoint() endpoint.Endpoint

Endpoint returns a usable endpoint that will invoke the gRPC specified by the client.

type ClientOption

type ClientOption func(*Client)

ClientOption sets an optional parameter for clients.

func ClientBefore

func ClientBefore(before ...RequestFunc) ClientOption

ClientBefore sets the RequestFuncs that are applied to the outgoing gRPC request before it's invoked.

type DecodeRequestFunc

type DecodeRequestFunc func(context.Context, interface{}) (request interface{}, err error)

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

type DecodeResponseFunc func(context.Context, interface{}) (response interface{}, err error)

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

type EncodeRequestFunc func(context.Context, interface{}) (request interface{}, err error)

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

type EncodeResponseFunc func(context.Context, interface{}) (response interface{}, err error)

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 context.Context, request interface{}) (context.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 RequestFunc

type RequestFunc func(context.Context, *metadata.MD) context.Context

RequestFunc may take information from an gRPC request and put it into a request context. In Servers, BeforeFuncs are executed prior to invoking the endpoint. In Clients, BeforeFuncs are executed after creating the request but prior to invoking the gRPC client.

func SetRequestHeader

func SetRequestHeader(key, val string) RequestFunc

SetRequestHeader returns a RequestFunc that sets the specified metadata key-value pair.

type ResponseFunc

type ResponseFunc func(context.Context, *metadata.MD)

ResponseFunc may take information from a request context and use it to manipulate the gRPC metadata header. ResponseFuncs are only executed in servers, after invoking the endpoint but prior to writing a response.

func SetResponseHeader

func SetResponseHeader(key, val string) ResponseFunc

SetResponseHeader returns a ResponseFunc that sets the specified metadata key-value pair.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps an endpoint and implements grpc.Handler.

func NewServer

func NewServer(
	ctx context.Context,
	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(grpcCtx context.Context, req interface{}) (context.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 ...ResponseFunc) 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 ...RequestFunc) 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.