Documentation ¶
Overview ¶
`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 ¶
Simple way of turning a multiple interceptors into a single interceptor. Here's an example for server chaining:
myServer := grpc.NewServer( grpc.ChainStreamInterceptor(loggingStream, monitoringStream, authStream)), grpc.ChainUnaryInterceptor(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(middleware.ChainUnaryClient(monitoringClientUnary, retryUnary)), grpc.WithStreamInterceptor(middleware.ChainStreamClient(monitoringClientStream, retryStream)), ) client = testpb.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.
The retry interceptor will call every interceptor that follows it whenever when a retry happens.
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 := middleware.WrapServerStream(stream) newStream.WrappedContext = context.WithValue(ctx, "user_id", "john@example.com") return handler(srv, newStream) }
Index ¶
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 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.
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()
Directories ¶
Path | Synopsis |
---|---|
interceptor is an internal package used by higher level middlewares.
|
interceptor is an internal package used by higher level middlewares. |
auth
`auth` a generic server-side auth middleware for gRPC.
|
`auth` a generic server-side auth middleware for gRPC. |
logging
logging is a "parent" package for gRPC logging middlewares.
|
logging is a "parent" package for gRPC logging middlewares. |
ratelimit
`ratelimit` a generic server-side ratelimit middleware for gRPC.
|
`ratelimit` a generic server-side ratelimit middleware for gRPC. |
recovery
`recovery` are interceptors that recover from gRPC handler panics.
|
`recovery` are interceptors that recover from gRPC handler panics. |
retry
`retry` provides client-side request retry logic for gRPC.
|
`retry` provides client-side request retry logic for gRPC. |
skip
`skip` allow users to skip interceptors in certain condition.
|
`skip` allow users to skip interceptors in certain condition. |
tags
`tags` adds a Tag object to the context that can be used by other middleware to add context about a request.
|
`tags` adds a Tag object to the context that can be used by other middleware to add context about a request. |
timeout
`grpc_timeout` are interceptors that timeout for gRPC client calls.
|
`grpc_timeout` are interceptors that timeout for gRPC client calls. |
tracing
tracing is a "parent" package for gRPC logging middlewares.
|
tracing is a "parent" package for gRPC logging middlewares. |
validator
`validator` is a generic request contents validator server-side middleware for gRPC.
|
`validator` is a generic request contents validator server-side middleware for gRPC. |
testing
|
|
util
|
|
backoffutils
Backoff Helper Utilities Implements common backoff features.
|
Backoff Helper Utilities Implements common backoff features. |