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.

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 addsvc.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.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

• Constants
• func EncodeKeyValue(key, val string) (string, string)
• func Interceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (resp interface{}, err error)
• type Client
  • func NewClient[REQ any, RES any](cc *grpc.ClientConn, serviceName string, method string, ...) *Client[REQ, RES]
  • func (c *Client[REQ, RES]) Endpoint() endpoint.Endpoint[REQ, RES]
• type ClientFinalizerFunc
• type ClientOption
  • func ClientAfter[REQ any, RES any](after ...ClientResponseFunc) ClientOption[REQ, RES]
  • func ClientBefore[REQ any, RES any](before ...ClientRequestFunc) ClientOption[REQ, RES]
  • func ClientFinalizer[REQ any, RES any](f ...ClientFinalizerFunc) ClientOption[REQ, RES]
• type ClientRequestFunc
  • func SetRequestHeader(key, val string) ClientRequestFunc
• type ClientResponseFunc
• type DecodeRequestFunc
• type DecodeResponseFunc
• type EncodeRequestFunc
• type EncodeResponseFunc
• type Handler
• type Server
  • func NewServer[REQ any, RES any](e endpoint.Endpoint[REQ, RES], dec DecodeRequestFunc[REQ], ...) *Server[REQ, RES]
  • func (s Server[REQ, RES]) ServeGRPC(ctx context.Context, req interface{}) (retctx context.Context, resp interface{}, err error)
• type ServerFinalizerFunc
• type ServerOption
  • func ServerAfter[REQ any, RES any](after ...ServerResponseFunc) ServerOption[REQ, RES]
  • func ServerBefore[REQ any, RES any](before ...ServerRequestFunc) ServerOption[REQ, RES]
  • func ServerErrorHandler[REQ any, RES any](errorHandler transport.ErrorHandler) ServerOption[REQ, RES]
  • func ServerErrorLogger[REQ any, RES any](logger log.Logger) ServerOption[REQ, RES]
  • func ServerFinalizer[REQ any, RES any](f ...ServerFinalizerFunc) ServerOption[REQ, RES]
• type ServerRequestFunc
• type ServerResponseFunc
  • func SetResponseHeader(key, val string) ServerResponseFunc
  • func SetResponseTrailer(key, val string) ServerResponseFunc

Constants

const (
	ContextKeyRequestMethod contextKey = iota
)

Functions

func EncodeKeyValue

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

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

func Interceptor

func Interceptor(
	ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler,
) (resp interface{}, err error)

Interceptor is a grpc UnaryInterceptor that injects the method name into context so it can be consumed by Go kit gRPC middlewares. The Interceptor typically is added at creation time of the grpc-go server. Like this: `grpc.NewServer(grpc.UnaryInterceptor(kitgrpc.Interceptor))`

Types

type Client

type Client[REQ any, RES any] struct {
	// contains filtered or unexported fields
}

Client wraps a gRPC connection and provides a method that implements endpoint.Endpoint.

func NewClient

func NewClient[REQ any, RES any](
	cc *grpc.ClientConn,
	serviceName string,
	method string,
	enc EncodeRequestFunc[REQ],
	dec DecodeResponseFunc[RES],
	grpcReply interface{},
	options ...ClientOption[REQ, RES],
) *Client[REQ, RES]

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[REQ, RES]) Endpoint

func (c *Client[REQ, RES]) Endpoint() endpoint.Endpoint[REQ, RES]

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

type ClientFinalizerFunc

type ClientFinalizerFunc func(ctx context.Context, err error)

ClientFinalizerFunc can be used to perform work at the end of a client gRPC request, after the response is returned. The principal intended use is for error logging. Additional response parameters are provided in the context under keys with the ContextKeyResponse prefix. Note: err may be nil. There maybe also no additional response parameters depending on when an error occurs.

type ClientOption

type ClientOption[REQ any, RES any] func(*Client[REQ, RES])

ClientOption sets an optional parameter for clients.

func ClientAfter

func ClientAfter[REQ any, RES any](after ...ClientResponseFunc) ClientOption[REQ, RES]

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[REQ any, RES any](before ...ClientRequestFunc) ClientOption[REQ, RES]

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

func ClientFinalizer

func ClientFinalizer[REQ any, RES any](f ...ClientFinalizerFunc) ClientOption[REQ, RES]

ClientFinalizer is executed at the end of every gRPC request. By default, no finalizer is registered.

type ClientRequestFunc

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

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

type DecodeRequestFunc[REQ any] func(context.Context, interface{}) (request REQ, 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[RES any] func(context.Context, interface{}) (response RES, 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[REQ any] func(context.Context, REQ) (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[RES any] func(context.Context, RES) (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 Server

type Server[REQ any, RES any] struct {
	// contains filtered or unexported fields
}

Server wraps an endpoint and implements grpc.Handler.

func NewServer

func NewServer[REQ any, RES any](
	e endpoint.Endpoint[REQ, RES],
	dec DecodeRequestFunc[REQ],
	enc EncodeResponseFunc[RES],
	options ...ServerOption[REQ, RES],
) *Server[REQ, RES]

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[REQ, RES]) ServeGRPC

func (s Server[REQ, RES]) ServeGRPC(ctx context.Context, req interface{}) (retctx context.Context, resp interface{}, err error)

ServeGRPC implements the Handler interface.

type ServerFinalizerFunc

type ServerFinalizerFunc func(ctx context.Context, err error)

ServerFinalizerFunc can be used to perform work at the end of an gRPC request, after the response has been written to the client.

type ServerOption

type ServerOption[REQ any, RES any] func(*Server[REQ, RES])

ServerOption sets an optional parameter for servers.

func ServerAfter

func ServerAfter[REQ any, RES any](after ...ServerResponseFunc) ServerOption[REQ, RES]

ServerAfter functions are executed on the gRPC response writer after the endpoint is invoked, but before anything is written to the client.

func ServerBefore

func ServerBefore[REQ any, RES any](before ...ServerRequestFunc) ServerOption[REQ, RES]

ServerBefore functions are executed on the gRPC request object before the request is decoded.

func ServerErrorHandler

func ServerErrorHandler[REQ any, RES any](errorHandler transport.ErrorHandler) ServerOption[REQ, RES]

ServerErrorHandler is used to handle non-terminal errors. By default, non-terminal errors are ignored.

func ServerErrorLogger

func ServerErrorLogger[REQ any, RES any](logger log.Logger) ServerOption[REQ, RES]

ServerErrorLogger is used to log non-terminal errors. By default, no errors are logged. Deprecated: Use ServerErrorHandler instead.

func ServerFinalizer

func ServerFinalizer[REQ any, RES any](f ...ServerFinalizerFunc) ServerOption[REQ, RES]

ServerFinalizer is executed at the end of every gRPC request. By default, no finalizer is registered.

type ServerRequestFunc

type ServerRequestFunc func(context.Context, metadata.MD) context.Context

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.