middleware

README

Go gRPC Middleware

This repository holds gRPC Go Middlewares: interceptors, helpers and utilities.

Middleware

gRPC Go has 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 patterns: auth, logging, tracing, metrics, validation, retries, rate limiting and more, which can be a great generic building blocks that make it easy to build multiple microservices easily.

Especially for observability signals (logging, tracing, metrics) interceptors offers semi-auto-instrumentation that improves consistency of your observability and allows great correlation techniques (e.g. exemplars and trace ID in logs). Demo-ed in examples.

This repository offers ready-to-use middlewares that implements gRPC interceptors with examples. In some cases dedicated projects offer great interceptors, so this repository skips those, and we link them in the interceptors list.

NOTE: Some middlewares are quite simple to write, so feel free to use this repo as template if you need. It's ok to copy some simpler interceptors if you need more flexibility. This repo can't support all the edge cases you might have.

Additional great feature of interceptors is the fact we can chain those. For example below you can find example server side chain of interceptors with full observabiliy correlation, auth and panic recovery:

	grpcSrv := grpc.NewServer(
		grpc.ChainUnaryInterceptor(
			// Order matters e.g. tracing interceptor have to create span first for the later exemplars to work.
			otelgrpc.UnaryServerInterceptor(),
			srvMetrics.UnaryServerInterceptor(grpcprom.WithExemplarFromContext(exemplarFromContext)),
			logging.UnaryServerInterceptor(interceptorLogger(rpcLogger), logging.WithFieldsFromContext(logTraceID)),
			selector.UnaryServerInterceptor(auth.UnaryServerInterceptor(authFn), selector.MatchFunc(allButHealthZ)),
			recovery.UnaryServerInterceptor(recovery.WithRecoveryHandler(grpcPanicRecoveryHandler)),
		),
		grpc.ChainStreamInterceptor(
			otelgrpc.StreamServerInterceptor(),
			srvMetrics.StreamServerInterceptor(grpcprom.WithExemplarFromContext(exemplarFromContext)),
			logging.StreamServerInterceptor(interceptorLogger(rpcLogger), logging.WithFieldsFromContext(logTraceID)),
			selector.StreamServerInterceptor(auth.StreamServerInterceptor(authFn), selector.MatchFunc(allButHealthZ)),
			recovery.StreamServerInterceptor(recovery.WithRecoveryHandler(grpcPanicRecoveryHandler)),
		),

This pattern offers clean and explicit shared functionality for all your gRPC methods. Full, buildable examples can be found in examples directory.

Interceptors

This list covers known interceptors that users use for their Go microservices (both in this repo and external). Click on each to see extended examples in examples_test.go (also available in pkg.go.dev)

All paths should work with go get <path>.

Auth

• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth - a customizable via AuthFunc piece of auth middleware.
• (external) google.golang.org/grpc/authz - more complex, customizable via auth polices (RBAC like), piece of auth middleware.

Observability

• Metrics:
  • github.com/grpc-ecosystem/go-grpc-middleware/providers/prometheus⚡ - Prometheus client-side and server-side monitoring middleware. Supports exemplars. Moved from deprecated now go-grpc-prometheus.
  • (external) go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc - official OpenTelemetry interceptors (metric and tracing).
• Logging with github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/logging - a customizable logging middleware offering extended per request logging. It requires logging adapter, see examples in interceptors/logging/examples for go-kit, log, logr, logrus, slog, zap and zerolog.
  • NOTE: Interceptors with context field injections need to be chained before the adapter function.
• Tracing:
  • (external) go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc - official OpenTelemetry interceptors (metric and tracing) as used in example.
  • (external) github.com/grpc-ecosystem/go-grpc-middleware/tracing/opentracing - deprecated OpenTracing client-side and server-side interceptors if you still need it!

Client

• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/retry - a generic gRPC response code retry mechanism, client-side middleware.
  • NOTE: grpc-go has native retries too with advanced policies (https://github.com/grpc/grpc-go/blob/v1.54.0/examples/features/retry/client/main.go)
• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/timeout - a generic gRPC request timeout, client-side middleware.

Server

• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/validator - codegen inbound message validation from .proto options.
• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/recovery - turn panics into gRPC errors (make sure to use those as "last" interceptor, so panic does not skip other interceptors).
• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit - grpc rate limiting by your own limiter.
• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/protovalidate - message validation from .proto options via protovalidate-go

Filtering Interceptor

• github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/selector - allow users to select given one or more interceptors in certain condition like matching service method.

Prerequisites

• Go: Any one of the three latest major releases are supported.

Structure of this repository

The main interceptors are available in the subdirectories of the interceptors directory e.g. interceptors/validator, interceptors/auth or interceptors/logging.

Some interceptors or utilities of interceptors requires opinionated code that depends on larger amount of dependencies. Those are places in providers directory as separate Go module, with separate versioning. For example providers/prometheus offer metrics middleware (there is no "interceptor/metrics" at the moment). The separate module, might be a little bit harder to discover and version in your go.mod, but it allows core interceptors to be ultra slim in terms of dependencies.

The interceptors directory also holds generic interceptors that accepts Reporter interface which allows creating your own middlewares with ease.

As you might notice this repository contains multiple modules with different versions (Go Module specifics). Refer to versions.yaml for current modules. We have main module of version 2.x.y and providers modules of lower versions. Since main module is v2, it's module path ends with v2:

go get github.com/grpc-ecosystem/go-grpc-middleware/v2/<package>

For providers modules and packages, since they are v1, no version is added to the path e.g.

go get github.com/grpc-ecosystem/go-grpc-middleware/providers/prometheus

Changes compared to v1

go-grpc-middleware v1 was created near 2015 and became a popular choice for gRPC users. However, many have changed since then. The main changes of v2 compared to v1:

• Path for separate, multiple Go modules in "providers". This allows to add in future specific providers for certain middlewares if needed. This allows interceptors to be extended without the dependency hell to the core framework (e.g. if use some other metric provider, do you want to import prometheus?). This allows greater extensibility.
• Loggers are removed. The interceptors/logging got simplified and writing adapter for each logger is straightforward. For convenience, we will maintain examples for popular providers in interceptors/logging/examples, but those are meant to be copied, not imported.
• grpc_opentracing interceptor was removed. This is because tracing instrumentation evolved. OpenTracing is deprecated and OpenTelemetry has now a superior tracing interceptor.
• grpc_ctxtags interceptor was removed. Custom tags can be added to logging fields using logging.InjectFields. Proto option to add logging field was clunky in practice and we don't see any use of it nowadays, so it's removed.
• One of the most powerful interceptor was imported from https://github.com/grpc-ecosystem/go-grpc-prometheus (repo is now deprecated). This consolidation allows easier maintenance, easier use and consistent API.
• Chain interceptors was removed, because grpc implemented one.
• Moved to the new proto API (google.golang.org/protobuf).
• All "deciders", so functions that decide what to do based on gRPC service name and method (aka "fullMethodName") are removed (!). Use github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/selector interceptor to select what method, type or service should use what interceptor.
• No more snake case package names. We have now single word meaningful package names. If you have collision in package names we recommend adding grpc prefix e.g. grpcprom "github.com/grpc-ecosystem/go-grpc-middleware/providers/prometheus".
• All the options (if any) are in the form of <package_name>.With<Option Name>, with extensibility to add more of them.
• v2 is the main (default) development branch.

For Maintainers: Release Process

This assumes we want to release minor version of any module:

1. Understand what has been change and what groups within versions has to be updated.
2. Update group version on v2 branch accordingly.
3. Create new tag for each module that has to be released. For the main module github.com/grpc-ecosystem/go-grpc-middleware/v2 the tag has no prefix (e.g. v2.20.1). For providers (sub modules), the tag version has to have form e.g. providers/<provider/v1.2.3. See https://github.com/golang/go/wiki/Modules#faqs--multi-module-repositories for details.
4. Once all tags are pushed, draft and create release on GitHub page, mentioning all changed tags in the title. Use auto-generation of notes and remove those that are not relevant for users (e.g. fixing docs).

License

go-grpc-middleware is released under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Overview

Package middleware

`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.WithChainUnaryInterceptor(monitoringClientUnary, retryUnary),
        grpc.WithChainStreamInterceptor(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 any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, 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 any, 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

• type WrappedServerStream
  • func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream
  • func (w *WrappedServerStream) Context() context.Context

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