grpc_middleware

README

Go gRPC Middleware - Interceptor Helpers

gRPC Go Interceptor middleware. Chain them, wrap them... arrange them in any pattern that normal http.Handler middleware would do :)

Interceptors

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, or monitoring (e.g. Prometheus)

Unfortunately out of the box, grpc-go allows you to have only one interceptor, which means you need to implement multiple interceptors manually... every time.

This repo contains tooling for gRPC interceptors, allowing you to achieve what many people do with HTTP middleware: auth, logging, pre-processing etc.

Chaining

Simple way of turning a multiple interceptors into a single interceptor. E.g.

Server

import "github.com/mwitkow/go-grpc-middleware"

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.

Client

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. Interestingly, the retry logic may perform more than one RPC.

How to write Interceptors?

It is incredibly useful to pass values around from one interceptor to another, 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 calling function.

Context Propagation

Unary (1:1) RPCs

This is relatively simple, since context.Context is appendable, for example:

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)
}

Streaming (N:1, 1:M, N:M) RPCs

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)
}

Status

This code has been inspired by the gRPC interceptor design discussion, and the upstream PR.

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

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
  • func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream
  • func (w *WrappedServerStream) Context() context.Context

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

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()