grpc_middleware

package module
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 15, 2023 License: Apache-2.0 Imports: 2 Imported by: 3,847

README

Go gRPC Middleware

Travis Build Go Report Card GoDoc SourceGraph codecov Apache 2.0 License Slack

gRPC Go Middleware: interceptors, helpers, utilities.

⚠️ Status

Version v2 is about to be released, with migration guide, which will replace v1. Try v2 and give us feedback!

Version v1 is currently in deprecation mode, which means only critical and safety bug fixes will be merged.

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 around the user call. It is a perfect way to implement common patterns: 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, 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 a Tag map to context, with data populated from request body
  • grpc_zap - integration of zap logging library into gRPC handlers.
  • grpc_logrus - integration of logrus logging library into gRPC handlers.
  • grpc_kit - integration of go-kit/log logging library into gRPC handlers.
  • grpc_grpc_logsettable - a wrapper around grpclog.LoggerV2 that allows to replace loggers in runtime (thread-safe).
Monitoring
Client
  • grpc_retry - a generic gRPC response code retry mechanism, client-side middleware
Server

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.

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 := grpc_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 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.

While this can be useful in some scenarios, it is generally advisable to use google.golang.org/grpc.ChainStreamInterceptor directly.

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.

While this can be useful in some scenarios, it is generally advisable to use google.golang.org/grpc.ChainUnaryInterceptor directly.

func WithStreamServerChain deprecated

func WithStreamServerChain(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption

WithStreamServerChain is a grpc.Server config option that accepts multiple stream interceptors. Basically syntactic sugar.

Deprecated: use google.golang.org/grpc.ChainStreamInterceptor instead.

func WithUnaryServerChain deprecated

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.

Deprecated: use google.golang.org/grpc.ChainUnaryInterceptor instead.

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
`grpc_auth` a generic server-side auth middleware for gRPC.
`grpc_auth` a generic server-side auth middleware for gRPC.
examples module
grpc_logging is a "parent" package for gRPC logging middlewares.
grpc_logging is a "parent" package for gRPC logging middlewares.
kit
`grpc_kit` is a gRPC logging middleware backed by go-kit loggers
`grpc_kit` is a gRPC logging middleware backed by go-kit loggers
kit/ctxkit
`ctxkit` is a ctxlogger that is backed by go-kit
`ctxkit` is a ctxlogger that is backed by go-kit
logrus
`grpc_logrus` is a gRPC logging middleware backed by Logrus loggers
`grpc_logrus` is a gRPC logging middleware backed by Logrus loggers
logrus/ctxlogrus
`ctxlogrus` is a ctxlogger that is backed by logrus
`ctxlogrus` is a ctxlogger that is backed by logrus
settable
grpc_logsettable contains a thread-safe wrapper around grpc-logging infrastructure.
grpc_logsettable contains a thread-safe wrapper around grpc-logging infrastructure.
zap
`grpc_zap` is a gRPC logging middleware backed by ZAP loggers
`grpc_zap` is a gRPC logging middleware backed by ZAP loggers
zap/ctxzap
`ctxzap` is a ctxlogger that is backed by Zap
`ctxzap` is a ctxlogger that is backed by Zap
providers
kit Module
logr Module
logrus Module
openmetrics Module
opentracing Module
phuslog Module
prometheus Module
tokenbucket Module
zap Module
zerolog Module
`ratelimit` a generic server-side ratelimit middleware for gRPC.
`ratelimit` a generic server-side ratelimit middleware for gRPC.
`grpc_recovery` are interceptors that recover from gRPC handler panics.
`grpc_recovery` are interceptors 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.
zap
tracing
opentracing
`grpc_opentracing` adds OpenTracing
`grpc_opentracing` adds OpenTracing
util
backoffutils
Backoff Helper Utilities
Backoff Helper Utilities
`grpc_validator` is a generic request contents validator server-side middleware for gRPC.
`grpc_validator` is a generic request contents validator server-side middleware for gRPC.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL