1# Go gRPC Middleware V2 2 3[![Travis Build](https://travis-ci.org/grpc-ecosystem/go-grpc-middleware.svg?branch=master)](https://travis-ci.org/grpc-ecosystem/go-grpc-middleware) 4[![Go Report Card](https://goreportcard.com/badge/github.com/grpc-ecosystem/go-grpc-middleware)](https://goreportcard.com/report/github.com/grpc-ecosystem/go-grpc-middleware) 5[![GoDoc](http://img.shields.io/badge/GoDoc-Reference-blue.svg)](https://godoc.org/github.com/grpc-ecosystem/go-grpc-middleware) 6[![SourceGraph](https://sourcegraph.com/github.com/grpc-ecosystem/go-grpc-middleware/-/badge.svg)](https://sourcegraph.com/github.com/grpc-ecosystem/go-grpc-middleware/?badge) 7[![codecov](https://codecov.io/gh/grpc-ecosystem/go-grpc-middleware/branch/master/graph/badge.svg)](https://codecov.io/gh/grpc-ecosystem/go-grpc-middleware) 8[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) 9[![quality: production](https://img.shields.io/badge/quality-production-orange.svg)](#status) 10[![Slack](https://img.shields.io/badge/slack-%23grpc--middleware-brightgreen)](https://slack.com/share/IRUQCFC23/9Tm7hxRFVKKNoajQfMOcUiIk/enQtODc4ODI4NTIyMDcxLWM5NDA0ZTE4Njg5YjRjYWZkMTI5MzQwNDY3YzBjMzE1YzdjOGM5ZjI1NDNiM2JmNzI2YjM5ODE5OTRiNTEyOWE) 11 12[gRPC Go](https://github.com/grpc/grpc-go) Middleware: interceptors, helpers, utilities. 13 14**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.** 15 16## Middleware 17 18[gRPC Go](https://github.com/grpc/grpc-go) recently acquired support for 19Interceptors, i.e. [middleware](https://medium.com/@matryer/writing-middleware-in-golang-and-how-go-makes-it-so-much-fun-4375c1246e81#.gv7tdlghs) 20that 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 21common patterns: auth, logging, message, validation, retries or monitoring. 22 23These are generic building blocks that make it easy to build multiple microservices easily. 24The purpose of this repository is to act as a go-to point for such reusable functionality. It contains 25some of them itself, but also will link to useful external repos. 26 27`middleware` itself provides support for chaining interceptors, here's an example: 28 29```go 30import "github.com/grpc-ecosystem/go-grpc-middleware/v2" 31 32myServer := grpc.NewServer( 33 grpc.StreamInterceptor(middleware.ChainStreamServer( 34 tags.StreamServerInterceptor(), 35 opentracing.StreamServerInterceptor(), 36 prometheus.StreamServerInterceptor, 37 zap.StreamServerInterceptor(zapLogger), 38 auth.StreamServerInterceptor(myAuthFunction), 39 recovery.StreamServerInterceptor(), 40 )), 41 grpc.UnaryInterceptor(middleware.ChainUnaryServer( 42 tags.UnaryServerInterceptor(), 43 opentracing.UnaryServerInterceptor(), 44 prometheus.UnaryServerInterceptor, 45 zap.UnaryServerInterceptor(zapLogger), 46 auth.UnaryServerInterceptor(myAuthFunction), 47 recovery.UnaryServerInterceptor(), 48 )), 49) 50``` 51 52## Interceptors 53 54*Please send a PR to add new interceptors or middleware to this list* 55 56#### Auth 57 * [`auth`](auth) - a customizable (via `AuthFunc`) piece of auth middleware 58 59#### Logging 60 * [`tags`](interceptors/tags) - a library that adds a `Tag` map to context, with data populated from request body 61 * [`zap`](providers/zap) - integration of [zap](https://github.com/uber-go/zap) logging library into gRPC handlers. 62 * [`logrus`](providers/logrus) - integration of [logrus](https://github.com/sirupsen/logrus) logging library into gRPC handlers. 63 * [`kit`](providers/kit) - integration of [go-kit](https://github.com/go-kit/kit/tree/master/log) logging library into gRPC handlers. 64 * [`zerolog`](providers/zerolog) - integration of [zerolog](https://github.com/rs/zerolog) logging Library into gRPC handlers. 65 66#### Monitoring 67 * [`grpc_prometheus`⚡](https://github.com/grpc-ecosystem/go-grpc-prometheus) - Prometheus client-side and server-side monitoring middleware 68 * [`opentracing`](interceptors/tracing) - [OpenTracing](http://opentracing.io/) client-side and server-side interceptors with support for streaming and handler-returned tags 69 70#### Client 71 * [`retry`](interceptors/retry) - a generic gRPC response code retry mechanism, client-side middleware 72 73#### Server 74 * [`validator`](interceptors/validator) - codegen inbound message validation from `.proto` options 75 * [`recovery`](interceptors/recovery) - turn panics into gRPC errors 76 * [`ratelimit`](interceptors/ratelimit) - grpc rate limiting by your own limiter 77 78 79## Status 80 81This code has been running in *production* since May 2016 as the basis of the gRPC micro services stack at [Improbable](https://improbable.io). 82 83Additional tooling will be added, and contributions are welcome. 84 85## License 86 87`go-grpc-middleware` is released under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details. 88