README.md

Documentation: github.com/grpc-ecosystem/go-grpc-middleware

     1# Go gRPC Middleware
     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://gophers.slack.com/archives/CNJL30P4P)
    11
    12[gRPC Go](https://github.com/grpc/grpc-go) Middleware: interceptors, helpers, utilities.
    13
    14## ⚠️  Status
    15
    16Version [v2](https://github.com/grpc-ecosystem/go-grpc-middleware/tree/v2) is about to be released, with migration guide, which will replace v1. Try v2 and give us feedback! 
    17
    18Version v1 is currently in deprecation mode, which means only critical and safety bug fixes will be merged.
    19
    20
    21## Middleware
    22
    23[gRPC Go](https://github.com/grpc/grpc-go) recently acquired support for
    24Interceptors, i.e. [middleware](https://medium.com/@matryer/writing-middleware-in-golang-and-how-go-makes-it-so-much-fun-4375c1246e81#.gv7tdlghs)
    25that 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
    26common patterns: auth, logging, message, validation, retries, or monitoring.
    27
    28These are generic building blocks that make it easy to build multiple microservices easily.
    29The purpose of this repository is to act as a go-to point for such reusable functionality. It contains
    30some of them itself, but also will link to useful external repos.
    31
    32`grpc_middleware` itself provides support for chaining interceptors, here's an example:
    33
    34```go
    35import "github.com/grpc-ecosystem/go-grpc-middleware"
    36
    37myServer := grpc.NewServer(
    38    grpc.StreamInterceptor(grpc_middleware.ChainStreamServer(
    39        grpc_ctxtags.StreamServerInterceptor(),
    40        grpc_opentracing.StreamServerInterceptor(),
    41        grpc_prometheus.StreamServerInterceptor,
    42        grpc_zap.StreamServerInterceptor(zapLogger),
    43        grpc_auth.StreamServerInterceptor(myAuthFunction),
    44        grpc_recovery.StreamServerInterceptor(),
    45    )),
    46    grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
    47        grpc_ctxtags.UnaryServerInterceptor(),
    48        grpc_opentracing.UnaryServerInterceptor(),
    49        grpc_prometheus.UnaryServerInterceptor,
    50        grpc_zap.UnaryServerInterceptor(zapLogger),
    51        grpc_auth.UnaryServerInterceptor(myAuthFunction),
    52        grpc_recovery.UnaryServerInterceptor(),
    53    )),
    54)
    55```
    56
    57## Interceptors
    58
    59_Please send a PR to add new interceptors or middleware to this list_
    60
    61#### Auth
    62
    63- [`grpc_auth`](auth) - a customizable (via `AuthFunc`) piece of auth middleware
    64
    65#### Logging
    66
    67- [`grpc_ctxtags`](tags/) - a library that adds a `Tag` map to context, with data populated from request body
    68- [`grpc_zap`](logging/zap/) - integration of [zap](https://github.com/uber-go/zap) logging library into gRPC handlers.
    69- [`grpc_logrus`](logging/logrus/) - integration of [logrus](https://github.com/sirupsen/logrus) logging library into gRPC handlers.
    70- [`grpc_kit`](logging/kit/) - integration of [go-kit/log](https://github.com/go-kit/log) logging library into gRPC handlers.
    71- [`grpc_grpc_logsettable`](logging/settable/) - a wrapper around `grpclog.LoggerV2` that allows to replace loggers in runtime (thread-safe).
    72
    73#### Monitoring
    74
    75- [`grpc_prometheus`⚡](https://github.com/grpc-ecosystem/go-grpc-prometheus) - Prometheus client-side and server-side monitoring middleware
    76- [`otgrpc`⚡](https://github.com/grpc-ecosystem/grpc-opentracing/tree/master/go/otgrpc) - [OpenTracing](http://opentracing.io/) client-side and server-side interceptors
    77- [`grpc_opentracing`](tracing/opentracing) - [OpenTracing](http://opentracing.io/) client-side and server-side interceptors with support for streaming and handler-returned tags
    78- [`otelgrpc`](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/google.golang.org/grpc/otelgrpc) - [OpenTelemetry](https://opentelemetry.io/) client-side and server-side interceptors
    79
    80#### Client
    81
    82- [`grpc_retry`](retry/) - a generic gRPC response code retry mechanism, client-side middleware
    83
    84#### Server
    85
    86- [`grpc_validator`](validator/) - codegen inbound message validation from `.proto` options
    87- [`grpc_recovery`](recovery/) - turn panics into gRPC errors
    88- [`ratelimit`](ratelimit/) - grpc rate limiting by your own limiter
    89
    90
    91## License
    92
    93`go-grpc-middleware` is released under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.
View as plain text