middleware

package module
Version: v2.0.0-rc.3 Latest Latest
Warning

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

Go to latest
Published: Sep 13, 2022 License: Apache-2.0 Imports: 2 Imported by: 26

README

Go gRPC Middleware V2

go Go Report Card GoDoc SourceGraph codecov Apache 2.0 License Slack

gRPC Go Middleware: interceptors, helpers, utilities.

NOTE: V2 is under development. If you want to be up to date, or better (!) help us improve go-grpc-middleware please follow on https://github.com/grpc-ecosystem/go-grpc-middleware/issues/275.

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 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.

middleware itself provides support for chaining interceptors, here's an example:

import "github.com/grpc-ecosystem/go-grpc-middleware/v2"

myServer := grpc.NewServer(
    grpc.ChainStreamInterceptor(
        tags.StreamServerInterceptor(),
        opentracing.StreamServerInterceptor(),
        prometheus.StreamServerInterceptor,
        zap.StreamServerInterceptor(zapLogger),
        auth.StreamServerInterceptor(myAuthFunction),
        recovery.StreamServerInterceptor(),
    ),
    grpc.ChainUnaryInterceptor(
        tags.UnaryServerInterceptor(),
        opentracing.UnaryServerInterceptor(),
        prometheus.UnaryServerInterceptor,
        zap.UnaryServerInterceptor(zapLogger),
        auth.UnaryServerInterceptor(myAuthFunction),
        recovery.UnaryServerInterceptor(),
    ),
)

Interceptors

Please send a PR to add new interceptors or middleware to this list

Auth
  • auth - a customizable (via AuthFunc) piece of auth middleware
Logging
  • tags - a library that adds a Tag map to context, with data populated from request body
  • zap - integration of zap logging library into gRPC handlers.
  • logrus - integration of logrus logging library into gRPC handlers.
  • kit - integration of go-kit/log logging library into gRPC handlers.
  • zerolog - integration of zerolog logging Library into gRPC handlers.
  • phuslog - integration of phuslog logging Library into gRPC handlers.
  • logr - integration of logr logging Library into gRPC handlers.
Monitoring
  • grpc_prometheus - Prometheus client-side and server-side monitoring middleware
  • opentracing - OpenTracing client-side and server-side interceptors with support for streaming and handler-returned tags
Client
  • retry - a generic gRPC response code retry mechanism, client-side middleware
  • timeout - a generic gRPC request timeout, client-side middleware
Server
  • validator - codegen inbound message validation from .proto options
  • recovery - turn panics into gRPC errors
  • ratelimit - grpc rate limiting by your own limiter
Utility
  • skip - allow users to skip interceptors in certain condition.

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

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.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
Package auth is a middleware that authenticates incoming gRPC requests.
Package auth is a middleware that authenticates incoming gRPC requests.
logging
Package logging is a "parent" package for gRPC logging middlewares.
Package logging is a "parent" package for gRPC logging middlewares.
ratelimit
Package ratelimit is a middleware that limits the rate of requests.
Package ratelimit is a middleware that limits the rate of requests.
recovery
Package recovery is a middleware that recovers from panics and logs the panic message.
Package recovery is a middleware that recovers from panics and logs the panic message.
retry
Package retry provides client-side request retry logic for gRPC.
Package retry provides client-side request retry logic for gRPC.
selector
Package selector
Package selector
skip
Package skip
Package skip
timeout
Package timeout is a middleware that responds with a timeout error after the given duration.
Package timeout is a middleware that responds with a timeout error after the given duration.
validator
Package validator
Package validator
testing
util
backoffutils
Backoff Helper Utilities
Backoff Helper Utilities

Jump to

Keyboard shortcuts

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