README
¶
Go gRPC Middleware
gRPC Go Middleware: interceptors, helpers, utilities.
Important The repo recently moved to github.com/grpc-ecosystem/go-grpc-middleware, please update your import paths.
Middleware
gRPC Go recently acquired support for Interceptors, i.e. middleware that is executed either on the gRPC Server before the request is passed onto the user's application logic, or on the gRPC client either around the user call. It is a perfect way to implement common patters: auth, logging, message, validation, retries or monitoring.
These are generic building blocks that make it easy to build multiple microservices easily. The purpose of this repository is to act as a go-to point for such reusable functionality. It contains some of them itself, but also will link to useful external repos.
grpc_middleware itself provides support for chaining interceptors. See Documentation, but here's an example:
import "github.com/grpc-ecosystem/go-grpc-middleware"
myServer := grpc.NewServer(
grpc.StreamInterceptor(grpc_middleware.ChainStreamServer(
grpc_ctxtags.StreamServerInterceptor(),
grpc_opentracing.StreamServerInterceptor(),
grpc_prometheus.StreamServerInterceptor,
grpc_zap.StreamServerInterceptor(zapLogger),
grpc_auth.StreamServerInterceptor(myAuthFunction),
grpc_recovery.StreamServerInterceptor(),
)),
grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
grpc_ctxtags.UnaryServerInterceptor(),
grpc_opentracing.UnaryServerInterceptor(),
grpc_prometheus.UnaryServerInterceptor,
grpc_zap.UnaryServerInterceptor(zapLogger),
grpc_auth.UnaryServerInterceptor(myAuthFunction),
grpc_recovery.UnaryServerInterceptor(),
)),
)
Interceptors
Please send a PR to add new interceptors or middleware to this list
Auth
grpc_auth- a customizable (via `AuthFunc) piece of auth middleware
Logging
grpc_ctxtags- a library that adds aTagmap to context, with data populated from request bodygrpc_zap- integration of zap logging library into gRPC handlers.grpc_logrus- integration of logrus logging library into gRPC handlers.
Monitoring
grpc_prometheus⚡ - Prometheus client-side and server-side monitoring middlewareotgrpc⚡ - OpenTracing client-side and server-side interceptorsgrpc_opentracing- OpenTracing client-side and server-side interceptors with support for streaming and handler-returned tags
Client
grpc_retry- a generic gRPC response code retry mechanism, client-side middleware
Server
grpc_validator- codegen inbound message validation from.protooptionsgrpc_recovery- turn panics into gRPC errors
Status
This code has been running in production since May 2016 as the basis of the gRPC micro services stack at Improbable.
Additional tooling will be added, and contributions are welcome.
License
go-grpc-middleware is released under the Apache 2.0 license. See the LICENSE file for details.
Documentation
¶
Overview ¶
`grpc_middleware` is a collection of gRPC middleware packages: interceptors, helpers and tools.
Middleware ¶
gRPC is a fantastic RPC middleware, which sees a lot of adoption in the Golang world. However, the upstream gRPC codebase is relatively bare bones.
This package, and most of its child packages provides commonly needed middleware for gRPC: client-side interceptors for retires, server-side interceptors for input validation and auth, functions for chaining said interceptors, metadata convenience methods and more.
Chaining ¶
By default, gRPC doesn't allow one to have more than one interceptor either on the client nor on the server side. `grpc_middleware` provides convenient chaining methods
Simple way of turning a multiple interceptors into a single interceptor. Here's an example for server chaining:
myServer := grpc.NewServer(
grpc.StreamInterceptor(grpc_middleware.ChainStreamServer(loggingStream, monitoringStream, authStream)),
grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(loggingUnary, monitoringUnary, authUnary),
)
These interceptors will be executed from left to right: logging, monitoring and auth.
Here's an example for client side chaining:
clientConn, err = grpc.Dial(
address,
grpc.WithUnaryInterceptor(grpc_middleware.ChainUnaryClient(monitoringClientUnary, retryUnary)),
grpc.WithStreamInterceptor(grpc_middleware.ChainStreamClient(monitoringClientStream, retryStream)),
)
client = pb_testproto.NewTestServiceClient(clientConn)
resp, err := client.PingEmpty(s.ctx, &myservice.Request{Msg: "hello"})
These interceptors will be executed from left to right: monitoring and then retry logic.
Writing Your Own ¶
Implementing your own interceptor is pretty trivial: there are interfaces for that. But the interesting bit exposing common data to handlers (and other middleware), similarly to HTTP Middleware design. For example, you may want to pass the identity of the caller from the auth interceptor all the way to the handling function.
For example, a client side interceptor example for auth looks like:
func FakeAuthUnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
newCtx := context.WithValue(ctx, "user_id", "john@example.com")
return handler(newCtx, req)
}
Unfortunately, it's not as easy for streaming RPCs. These have the `context.Context` embedded within the `grpc.ServerStream` object. To pass values through context, a wrapper (`WrappedServerStream`) is needed. For example:
func FakeAuthStreamingInterceptor(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
newStream := grpc_middleware.WrapServerStream(stream)
newStream.WrappedContext = context.WithValue(ctx, "user_id", "john@example.com")
return handler(srv, stream)
}
Index ¶
- func ChainStreamClient(interceptors ...grpc.StreamClientInterceptor) grpc.StreamClientInterceptor
- func ChainStreamServer(interceptors ...grpc.StreamServerInterceptor) grpc.StreamServerInterceptor
- func ChainUnaryClient(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor
- func ChainUnaryServer(interceptors ...grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor
- func WithStreamServerChain(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption
- func WithUnaryServerChain(interceptors ...grpc.UnaryServerInterceptor) grpc.ServerOption
- type WrappedServerStream
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ChainStreamClient ¶
func ChainStreamClient(interceptors ...grpc.StreamClientInterceptor) grpc.StreamClientInterceptor
ChainStreamClient creates a single interceptor out of a chain of many interceptors.
Execution is done in left-to-right order, including passing of context. For example ChainStreamClient(one, two, three) will execute one before two before three.
func ChainStreamServer ¶
func ChainStreamServer(interceptors ...grpc.StreamServerInterceptor) grpc.StreamServerInterceptor
ChainStreamServer creates a single interceptor out of a chain of many interceptors.
Execution is done in left-to-right order, including passing of context. For example ChainUnaryServer(one, two, three) will execute one before two before three. If you want to pass context between interceptors, use WrapServerStream.
func ChainUnaryClient ¶
func ChainUnaryClient(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor
ChainUnaryClient creates a single interceptor out of a chain of many interceptors.
Execution is done in left-to-right order, including passing of context. For example ChainUnaryClient(one, two, three) will execute one before two before three.
func ChainUnaryServer ¶
func ChainUnaryServer(interceptors ...grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor
ChainUnaryServer creates a single interceptor out of a chain of many interceptors.
Execution is done in left-to-right order, including passing of context. For example ChainUnaryServer(one, two, three) will execute one before two before three, and three will see context changes of one and two.
func WithStreamServerChain ¶
func WithStreamServerChain(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption
WithStreamServerChain is a grpc.Server config option that accepts multiple stream interceptors. Basically syntactic sugar.
func WithUnaryServerChain ¶
func WithUnaryServerChain(interceptors ...grpc.UnaryServerInterceptor) grpc.ServerOption
Chain creates a single interceptor out of a chain of many interceptors.
WithUnaryServerChain is a grpc.Server config option that accepts multiple unary interceptors. Basically syntactic sugar.
Types ¶
type WrappedServerStream ¶
type WrappedServerStream struct {
grpc.ServerStream
// WrappedContext is the wrapper's own Context. You can assign it.
WrappedContext context.Context
}
WrappedServerStream is a thin wrapper around grpc.ServerStream that allows modifying context.
func WrapServerStream ¶
func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream
WrapServerStream returns a ServerStream that has the ability to overwrite context.
func (*WrappedServerStream) Context ¶
func (w *WrappedServerStream) Context() context.Context
Context returns the wrapper's WrappedContext, overwriting the nested grpc.ServerStream.Context()
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
`grpc_auth` a generic server-side auth middleware for gRPC.
|
`grpc_auth` a generic server-side auth middleware for gRPC. |
|
grpc_logging is a "parent" package for gRPC logging middlewares General functionality of all middleware All logging middleware have an `Extract(ctx)` function that provides a request-scoped logger with gRPC-related fields (service and method names).
|
grpc_logging is a "parent" package for gRPC logging middlewares General functionality of all middleware All logging middleware have an `Extract(ctx)` function that provides a request-scoped logger with gRPC-related fields (service and method names). |
|
logrus
`grpc_logrus` is a gRPC logging middleware backed by Logrus loggers It accepts a user-configured `logrus.Entry` that will be used for logging completed gRPC calls.
|
`grpc_logrus` is a gRPC logging middleware backed by Logrus loggers It accepts a user-configured `logrus.Entry` that will be used for logging completed gRPC calls. |
|
zap
`grpc_zap` is a gRPC logging middleware backed by ZAP loggers It accepts a user-configured `zap.Logger` that will be used for logging completed gRPC calls.
|
`grpc_zap` is a gRPC logging middleware backed by ZAP loggers It accepts a user-configured `zap.Logger` that will be used for logging completed gRPC calls. |
|
`grpc_recovery` are intereceptors that recover from gRPC handler panics.
|
`grpc_recovery` are intereceptors that recover from gRPC handler panics. |
|
`grpc_retry` provides client-side request retry logic for gRPC.
|
`grpc_retry` provides client-side request retry logic for gRPC. |
|
`grpc_ctxtags` adds a Tag object to the context that can be used by other middleware to add context about a request.
|
`grpc_ctxtags` adds a Tag object to the context that can be used by other middleware to add context about a request. |
|
gogotestproto
Package mwitkow_testproto is a generated protocol buffer package.
|
Package mwitkow_testproto is a generated protocol buffer package. |
|
testproto
Package mwitkow_testproto is a generated protocol buffer package.
|
Package mwitkow_testproto is a generated protocol buffer package. |
|
tracing
|
|
|
opentracing
`grpc_opentracing` adds OpenTracing OpenTracing Interceptors These are both client-side and server-side interceptors for OpenTracing.
|
`grpc_opentracing` adds OpenTracing OpenTracing Interceptors These are both client-side and server-side interceptors for OpenTracing. |
|
util
|
|
|
backoffutils
Backoff Helper Utilities Implements common backoff features.
|
Backoff Helper Utilities Implements common backoff features. |
|
`grpc_validator` a generic request contents validator server-side middleware for gRPC.
|
`grpc_validator` a generic request contents validator server-side middleware for gRPC. |