From 4832df01553a810b8e3404b95743d01c9ab5313f Mon Sep 17 00:00:00 2001 From: Dominic Green Date: Fri, 4 Jan 2019 16:03:21 +0000 Subject: [PATCH] Remove generation of docs (#183) Docs will now be only in code / in godoc.org. We should remove the auto generation of docs from this repo, as much as it was nice to have them alongside the code in github it is normal go practice to look for most documentation via godoc.org. The libraries that we have been using to generate the github markdown are no longer maintained and updated in the godoc codebase itself have meant that we would also have to update these dependant libraries ... which I do not think we should take. --- .travis.yml | 1 - DOC.md | 166 ------------ README.md | 4 +- auth/DOC.md | 148 ----------- auth/README.md | 1 - logging/DOC.md | 91 ------- logging/README.md | 1 - logging/logrus/DOC.md | 391 ---------------------------- logging/logrus/README.md | 1 - logging/logrus/ctxlogrus/DOC.md | 93 ------- logging/logrus/ctxlogrus/README.md | 58 ----- logging/zap/DOC.md | 402 ----------------------------- logging/zap/README.md | 1 - logging/zap/ctxzap/DOC.md | 105 -------- logging/zap/ctxzap/README.md | 65 ----- makefile | 12 +- recovery/DOC.md | 107 -------- recovery/README.md | 1 - retry/DOC.md | 255 ------------------ retry/README.md | 1 - scripts/docs.sh | 42 --- tags/DOC.md | 182 ------------- tags/README.md | 1 - tracing/opentracing/DOC.md | 118 --------- tracing/opentracing/README.md | 1 - util/metautils/DOC.md | 114 -------- util/metautils/README.md | 1 - validator/DOC.md | 80 ------ validator/README.md | 73 ------ 29 files changed, 4 insertions(+), 2512 deletions(-) delete mode 100644 DOC.md delete mode 100644 auth/DOC.md delete mode 120000 auth/README.md delete mode 100644 logging/DOC.md delete mode 120000 logging/README.md delete mode 100644 logging/logrus/DOC.md delete mode 120000 logging/logrus/README.md delete mode 100644 logging/logrus/ctxlogrus/DOC.md delete mode 100644 logging/logrus/ctxlogrus/README.md delete mode 100644 logging/zap/DOC.md delete mode 120000 logging/zap/README.md delete mode 100644 logging/zap/ctxzap/DOC.md delete mode 100644 logging/zap/ctxzap/README.md delete mode 100644 recovery/DOC.md delete mode 120000 recovery/README.md delete mode 100644 retry/DOC.md delete mode 120000 retry/README.md delete mode 100755 scripts/docs.sh delete mode 100644 tags/DOC.md delete mode 120000 tags/README.md delete mode 100644 tracing/opentracing/DOC.md delete mode 120000 tracing/opentracing/README.md delete mode 100644 util/metautils/DOC.md delete mode 120000 util/metautils/README.md delete mode 100644 validator/DOC.md delete mode 100644 validator/README.md diff --git a/.travis.yml b/.travis.yml index 2fc21dd6f..702fa5b72 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,7 +15,6 @@ install: - dep ensure script: - - make checkdocs - make test after_success: diff --git a/DOC.md b/DOC.md deleted file mode 100644 index 511d953a8..000000000 --- a/DOC.md +++ /dev/null @@ -1,166 +0,0 @@ -# grpc_middleware -`import "github.com/grpc-ecosystem/go-grpc-middleware"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## 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, stream) - } - -## Imported Packages - -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) - -## Index -* [func ChainStreamClient(interceptors ...grpc.StreamClientInterceptor) grpc.StreamClientInterceptor](#ChainStreamClient) -* [func ChainStreamServer(interceptors ...grpc.StreamServerInterceptor) grpc.StreamServerInterceptor](#ChainStreamServer) -* [func ChainUnaryClient(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor](#ChainUnaryClient) -* [func ChainUnaryServer(interceptors ...grpc.UnaryServerInterceptor) grpc.UnaryServerInterceptor](#ChainUnaryServer) -* [func WithStreamServerChain(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption](#WithStreamServerChain) -* [func WithUnaryServerChain(interceptors ...grpc.UnaryServerInterceptor) grpc.ServerOption](#WithUnaryServerChain) -* [type WrappedServerStream](#WrappedServerStream) - * [func WrapServerStream(stream grpc.ServerStream) \*WrappedServerStream](#WrapServerStream) - * [func (w \*WrappedServerStream) Context() context.Context](#WrappedServerStream.Context) - -#### Package files -[chain.go](./chain.go) [doc.go](./doc.go) [wrappers.go](./wrappers.go) - -## func [ChainStreamClient](./chain.go#L136) -``` go -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](./chain.go#L58) -``` go -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. - -## func [ChainUnaryClient](./chain.go#L97) -``` go -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](./chain.go#L18) -``` go -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. - -## func [WithStreamServerChain](./chain.go#L181) -``` go -func WithStreamServerChain(interceptors ...grpc.StreamServerInterceptor) grpc.ServerOption -``` -WithStreamServerChain is a grpc.Server config option that accepts multiple stream interceptors. -Basically syntactic sugar. - -## func [WithUnaryServerChain](./chain.go#L175) -``` go -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. - -## type [WrappedServerStream](./wrappers.go#L12-L16) -``` go -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](./wrappers.go#L24) -``` go -func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream -``` -WrapServerStream returns a ServerStream that has the ability to overwrite context. - -### func (\*WrappedServerStream) [Context](./wrappers.go#L19) -``` go -func (w *WrappedServerStream) Context() context.Context -``` -Context returns the wrapper's WrappedContext, overwriting the nested grpc.ServerStream.Context() - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/README.md b/README.md index 52e53733c..224069b22 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,6 @@ [gRPC Go](https://github.com/grpc/grpc-go) Middleware: interceptors, helpers, utilities. -**Important** The repo recently moved to `github.com/grpc-ecosystem/go-grpc-middleware`, please update your import paths. - ## Middleware [gRPC Go](https://github.com/grpc/grpc-go) recently acquired support for @@ -24,7 +22,7 @@ These are generic building blocks that make it easy to build multiple microservi 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. See [Documentation](DOC.md), but here's an example: +`grpc_middleware` itself provides support for chaining interceptors, here's an example: ```go import "github.com/grpc-ecosystem/go-grpc-middleware" diff --git a/auth/DOC.md b/auth/DOC.md deleted file mode 100644 index 5834112b0..000000000 --- a/auth/DOC.md +++ /dev/null @@ -1,148 +0,0 @@ -# grpc_auth -`import "github.com/grpc-ecosystem/go-grpc-middleware/auth"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`grpc_auth` a generic server-side auth middleware for gRPC. - -### Server Side Auth Middleware -It allows for easy assertion of `:authorization` headers in gRPC calls, be it HTTP Basic auth, or -OAuth2 Bearer tokens. - -The middleware takes a user-customizable `AuthFunc`, which can be customized to verify and extract -auth information from the request. The extracted information can be put in the `context.Context` of -handlers downstream for retrieval. - -It also allows for per-service implementation overrides of `AuthFunc`. See `ServiceAuthFuncOverride`. - -Please see examples for simple examples of use. - -#### Example: - -
-Click to expand code. - -```go -package grpc_auth_test - -import ( - "github.com/grpc-ecosystem/go-grpc-middleware/auth" - "github.com/grpc-ecosystem/go-grpc-middleware/tags" - "golang.org/x/net/context" - "google.golang.org/grpc" - "google.golang.org/grpc/codes" -) - -var ( - cc *grpc.ClientConn -) - -func parseToken(token string) (struct{}, error) { - return struct{}{}, nil -} - -func userClaimFromToken(struct{}) string { - return "foobar" -} - -// Simple example of server initialization code. -func Example_serverConfig() { - exampleAuthFunc := func(ctx context.Context) (context.Context, error) { - token, err := grpc_auth.AuthFromMD(ctx, "bearer") - if err != nil { - return nil, err - } - tokenInfo, err := parseToken(token) - if err != nil { - return nil, grpc.Errorf(codes.Unauthenticated, "invalid auth token: %v", err) - } - grpc_ctxtags.Extract(ctx).Set("auth.sub", userClaimFromToken(tokenInfo)) - newCtx := context.WithValue(ctx, "tokenInfo", tokenInfo) - return newCtx, nil - } - - _ = grpc.NewServer( - grpc.StreamInterceptor(grpc_auth.StreamServerInterceptor(exampleAuthFunc)), - grpc.UnaryInterceptor(grpc_auth.UnaryServerInterceptor(exampleAuthFunc)), - ) -} -``` - -
- -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware](./..) -- [github.com/grpc-ecosystem/go-grpc-middleware/util/metautils](./../util/metautils) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) - -## Index -* [func AuthFromMD(ctx context.Context, expectedScheme string) (string, error)](#AuthFromMD) -* [func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor](#UnaryServerInterceptor) -* [type AuthFunc](#AuthFunc) -* [type ServiceAuthFuncOverride](#ServiceAuthFuncOverride) - -#### Examples -* [Package (ServerConfig)](#example__serverConfig) - -#### Package files -[auth.go](./auth.go) [doc.go](./doc.go) [metadata.go](./metadata.go) - -## func [AuthFromMD](./metadata.go#L24) -``` go -func AuthFromMD(ctx context.Context, expectedScheme string) (string, error) -``` -AuthFromMD is a helper function for extracting the :authorization header from the gRPC metadata of the request. - -It expects the `:authorization` header to be of a certain scheme (e.g. `basic`, `bearer`), in a -case-insensitive format (see rfc2617, sec 1.2). If no such authorization is found, or the token -is of wrong scheme, an error with gRPC status `Unauthenticated` is returned. - -## func [StreamServerInterceptor](./auth.go#L51) -``` go -func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new unary server interceptors that performs per-request auth. - -## func [UnaryServerInterceptor](./auth.go#L34) -``` go -func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptors that performs per-request auth. - -## type [AuthFunc](./auth.go#L23) -``` go -type AuthFunc func(ctx context.Context) (context.Context, error) -``` -AuthFunc is the pluggable function that performs authentication. - -The passed in `Context` will contain the gRPC metadata.MD object (for header-based authentication) and -the peer.Peer information that can contain transport-based credentials (e.g. `credentials.AuthInfo`). - -The returned context will be propagated to handlers, allowing user changes to `Context`. However, -please make sure that the `Context` returned is a child `Context` of the one passed in. - -If error is returned, its `grpc.Code()` will be returned to the user as well as the verbatim message. -Please make sure you use `codes.Unauthenticated` (lacking auth) and `codes.PermissionDenied` -(authed, but lacking perms) appropriately. - -## type [ServiceAuthFuncOverride](./auth.go#L29-L31) -``` go -type ServiceAuthFuncOverride interface { - AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error) -} -``` -ServiceAuthFuncOverride allows a given gRPC service implementation to override the global `AuthFunc`. - -If a service implements the AuthFuncOverride method, it takes precedence over the `AuthFunc` method, -and will be called instead of AuthFunc for all method invocations within that service. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/auth/README.md b/auth/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/auth/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/logging/DOC.md b/logging/DOC.md deleted file mode 100644 index 9deb4722c..000000000 --- a/logging/DOC.md +++ /dev/null @@ -1,91 +0,0 @@ -# grpc_logging -`import "github.com/grpc-ecosystem/go-grpc-middleware/logging"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## Overview -grpc_logging is a "parent" package for gRPC logging middlewares. - -### General functionality of all middleware -The gRPC logging middleware populates request-scoped data to `grpc_ctxtags.Tags` that relate to the current gRPC call -(e.g. service and method names). - -Once the gRPC logging middleware has added the gRPC specific Tags to the ctx they will then be written with the logs -that are made using the `ctx_logrus` or `ctx_zap` loggers. - -All logging middleware will emit a final log statement. It is based on the error returned by the handler function, -the gRPC status code, an error (if any) and it will emit at a level controlled via `WithLevels`. - -### This parent package -This particular package is intended for use by other middleware, logging or otherwise. It contains interfaces that other -logging middlewares *could* share . This allows code to be shared between different implementations. - -### Field names -All field names of loggers follow the OpenTracing semantics definitions, with `grpc.` prefix if needed: -https://github.com/opentracing/specification/blob/master/semantic_conventions.md - -### Implementations -There are two implementations at the moment: logrus and zap - -See relevant packages below. - -## Imported Packages - -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) - -## Index -* [func DefaultDeciderMethod(fullMethodName string, err error) bool](#DefaultDeciderMethod) -* [func DefaultErrorToCode(err error) codes.Code](#DefaultErrorToCode) -* [type ClientPayloadLoggingDecider](#ClientPayloadLoggingDecider) -* [type Decider](#Decider) -* [type ErrorToCode](#ErrorToCode) -* [type ServerPayloadLoggingDecider](#ServerPayloadLoggingDecider) - -#### Package files -[common.go](./common.go) [doc.go](./doc.go) - -## func [DefaultDeciderMethod](./common.go#L25) -``` go -func DefaultDeciderMethod(fullMethodName string, err error) bool -``` -DefaultDeciderMethod is the default implementation of decider to see if you should log the call -by default this if always true so all calls are logged - -## func [DefaultErrorToCode](./common.go#L16) -``` go -func DefaultErrorToCode(err error) codes.Code -``` - -## type [ClientPayloadLoggingDecider](./common.go#L35) -``` go -type ClientPayloadLoggingDecider func(ctx context.Context, fullMethodName string) bool -``` -ClientPayloadLoggingDecider is a user-provided function for deciding whether to log the client-side -request/response payloads - -## type [Decider](./common.go#L21) -``` go -type Decider func(fullMethodName string, err error) bool -``` -Decider function defines rules for suppressing any interceptor logs - -## type [ErrorToCode](./common.go#L14) -``` go -type ErrorToCode func(err error) codes.Code -``` -ErrorToCode function determines the error code of an error -This makes using custom errors with grpc middleware easier - -## type [ServerPayloadLoggingDecider](./common.go#L31) -``` go -type ServerPayloadLoggingDecider func(ctx context.Context, fullMethodName string, servingObject interface{}) bool -``` -ServerPayloadLoggingDecider is a user-provided function for deciding whether to log the server-side -request/response payloads - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/logging/README.md b/logging/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/logging/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/logging/logrus/DOC.md b/logging/logrus/DOC.md deleted file mode 100644 index 7a1bb9394..000000000 --- a/logging/logrus/DOC.md +++ /dev/null @@ -1,391 +0,0 @@ -# grpc_logrus -`import "github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`grpc_logrus` is a gRPC logging middleware backed by Logrus loggers - -It accepts a user-configured `logrus.Entry` that will be used for logging completed gRPC calls. The same -`logrus.Entry` will be used for logging completed gRPC calls, and be populated into the `context.Context` passed into gRPC handler code. - -On calling `StreamServerInterceptor` or `UnaryServerInterceptor` this logging middleware will add gRPC call information -to the ctx so that it will be present on subsequent use of the `ctxlogrus` logger. - -This package also implements request and response *payload* logging, both for server-side and client-side. These will be -logged as structured `jsonpb` fields for every message received/sent (both unary and streaming). For that please use -`Payload*Interceptor` functions for that. Please note that the user-provided function that determines whetether to log -the full request/response payload needs to be written with care, this can significantly slow down gRPC. - -If a deadline is present on the gRPC request the grpc.request.deadline tag is populated when the request begins. grpc.request.deadline -is a string representing the time (RFC3339) when the current call will expire. - -Logrus can also be made as a backend for gRPC library internals. For that use `ReplaceGrpcLogger`. - -*Server Interceptor* -Below is a JSON formatted example of a log that would be logged by the server interceptor: - - { - "level": "info", // string logrus log levels - "msg": "finished unary call", // string log message - "grpc.code": "OK", // string grpc status code - "grpc.method": "Ping", // string method name - "grpc.service": "mwitkow.testproto.TestService", // string full name of the called service - "grpc.start_time": "2006-01-02T15:04:05Z07:00", // string RFC3339 representation of the start time - "grpc.request.deadline": "2006-01-02T15:04:05Z07:00", // string RFC3339 deadline of the current request if supplied - "grpc.request.value": "something", // string value on the request - "grpc.time_ms": 1.234, // float32 run time of the call in ms - "peer.address": { - "IP": "127.0.0.1", // string IP address of calling party - "Port": 60216, // int port call is coming in on - "Zone": "" // string peer zone for caller - }, - "span.kind": "server", // string client | server - "system": "grpc" // string - - "custom_field": "custom_value", // string user defined field - "custom_tags.int": 1337, // int user defined tag on the ctx - "custom_tags.string": "something", // string user defined tag on the ctx - } - -*Payload Interceptor* -Below is a JSON formatted example of a log that would be logged by the payload interceptor: - - { - "level": "info", // string logrus log levels - "msg": "client request payload logged as grpc.request.content", // string log message - - "grpc.request.content": { // object content of RPC request - "value": "something", // string defined by caller - "sleepTimeMs": 9999 // int defined by caller - }, - "grpc.method": "Ping", // string method being called - "grpc.service": "mwitkow.testproto.TestService", // string service being called - "span.kind": "client", // string client | server - "system": "grpc" // string - } - -Note - due to implementation ZAP differs from Logrus in the "grpc.request.content" object by having an inner "msg" object. - -Please see examples and tests for examples of use. - -#### Example: - -
-Click to expand code. - -```go -// Logrus entry is used, allowing pre-definition of certain fields by the user. -logrusEntry := logrus.NewEntry(logrusLogger) -// Shared options for the logger, with a custom gRPC code to log level function. -opts := []grpc_logrus.Option{ - grpc_logrus.WithLevels(customFunc), -} -// Make sure that log statements internal to gRPC library are logged using the logrus Logger as well. -grpc_logrus.ReplaceGrpcLogger(logrusEntry) -// Create a server, make sure we put the grpc_ctxtags context before everything else. -_ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), - grpc_logrus.UnaryServerInterceptor(logrusEntry, opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), - grpc_logrus.StreamServerInterceptor(logrusEntry, opts...), - ), -) -``` - -
- -#### Example: - -
-Click to expand code. - -```go -// Logrus entry is used, allowing pre-definition of certain fields by the user. -logrusEntry := logrus.NewEntry(logrusLogger) -// Shared options for the logger, with a custom duration to log field function. -opts := []grpc_logrus.Option{ - grpc_logrus.WithDurationField(func(duration time.Duration) (key string, value interface{}) { - return "grpc.time_ns", duration.Nanoseconds() - }), -} -_ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(), - grpc_logrus.UnaryServerInterceptor(logrusEntry, opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(), - grpc_logrus.StreamServerInterceptor(logrusEntry, opts...), - ), -) -``` - -
- -## Imported Packages - -- [github.com/golang/protobuf/jsonpb](https://godoc.org/github.com/golang/protobuf/jsonpb) -- [github.com/golang/protobuf/proto](https://godoc.org/github.com/golang/protobuf/proto) -- [github.com/grpc-ecosystem/go-grpc-middleware](./../..) -- [github.com/grpc-ecosystem/go-grpc-middleware/logging](./..) -- [github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/ctxlogrus](./ctxlogrus) -- [github.com/grpc-ecosystem/go-grpc-middleware/tags/logrus](./../../tags/logrus) -- [github.com/sirupsen/logrus](https://godoc.org/github.com/sirupsen/logrus) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) -- [google.golang.org/grpc/grpclog](https://godoc.org/google.golang.org/grpc/grpclog) - -## Index -* [Variables](#pkg-variables) -* [func AddFields(ctx context.Context, fields logrus.Fields)](#AddFields) -* [func DefaultClientCodeToLevel(code codes.Code) logrus.Level](#DefaultClientCodeToLevel) -* [func DefaultCodeToLevel(code codes.Code) logrus.Level](#DefaultCodeToLevel) -* [func DurationToDurationField(duration time.Duration) (key string, value interface{})](#DurationToDurationField) -* [func DurationToTimeMillisField(duration time.Duration) (key string, value interface{})](#DurationToTimeMillisField) -* [func Extract(ctx context.Context) \*logrus.Entry](#Extract) -* [func PayloadStreamClientInterceptor(entry \*logrus.Entry, decider grpc\_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor](#PayloadStreamClientInterceptor) -* [func PayloadStreamServerInterceptor(entry \*logrus.Entry, decider grpc\_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor](#PayloadStreamServerInterceptor) -* [func PayloadUnaryClientInterceptor(entry \*logrus.Entry, decider grpc\_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor](#PayloadUnaryClientInterceptor) -* [func PayloadUnaryServerInterceptor(entry \*logrus.Entry, decider grpc\_logging.ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor](#PayloadUnaryServerInterceptor) -* [func ReplaceGrpcLogger(logger \*logrus.Entry)](#ReplaceGrpcLogger) -* [func StreamClientInterceptor(entry \*logrus.Entry, opts ...Option) grpc.StreamClientInterceptor](#StreamClientInterceptor) -* [func StreamServerInterceptor(entry \*logrus.Entry, opts ...Option) grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryClientInterceptor(entry \*logrus.Entry, opts ...Option) grpc.UnaryClientInterceptor](#UnaryClientInterceptor) -* [func UnaryServerInterceptor(entry \*logrus.Entry, opts ...Option) grpc.UnaryServerInterceptor](#UnaryServerInterceptor) -* [type CodeToLevel](#CodeToLevel) -* [type DurationToField](#DurationToField) -* [type Option](#Option) - * [func WithCodes(f grpc\_logging.ErrorToCode) Option](#WithCodes) - * [func WithDecider(f grpc\_logging.Decider) Option](#WithDecider) - * [func WithDurationField(f DurationToField) Option](#WithDurationField) - * [func WithLevels(f CodeToLevel) Option](#WithLevels) - -#### Examples -* [Extract (Unary)](#example_Extract_unary) -* [WithDecider](#example_WithDecider) -* [Package (Initialization)](#example__initialization) -* [Package (InitializationWithDurationFieldOverride)](#example__initializationWithDurationFieldOverride) - -#### Package files -[client_interceptors.go](./client_interceptors.go) [context.go](./context.go) [doc.go](./doc.go) [grpclogger.go](./grpclogger.go) [options.go](./options.go) [payload_interceptors.go](./payload_interceptors.go) [server_interceptors.go](./server_interceptors.go) - -## Variables -``` go -var ( - // SystemField is used in every log statement made through grpc_logrus. Can be overwritten before any initialization code. - SystemField = "system" - - // KindField describes the log gield used to incicate whether this is a server or a client log statment. - KindField = "span.kind" -) -``` -``` go -var DefaultDurationToField = DurationToTimeMillisField -``` -DefaultDurationToField is the default implementation of converting request duration to a log field (key and value). - -``` go -var ( - // JsonPbMarshaller is the marshaller used for serializing protobuf messages. - JsonPbMarshaller = &jsonpb.Marshaler{} -) -``` - -## func [AddFields](./context.go#L11) -``` go -func AddFields(ctx context.Context, fields logrus.Fields) -``` -AddFields adds logrus fields to the logger. -Deprecated: should use the ctxlogrus.Extract instead - -## func [DefaultClientCodeToLevel](./options.go#L129) -``` go -func DefaultClientCodeToLevel(code codes.Code) logrus.Level -``` -DefaultClientCodeToLevel is the default implementation of gRPC return codes to log levels for client side. - -## func [DefaultCodeToLevel](./options.go#L87) -``` go -func DefaultCodeToLevel(code codes.Code) logrus.Level -``` -DefaultCodeToLevel is the default implementation of gRPC return codes to log levels for server side. - -## func [DurationToDurationField](./options.go#L179) -``` go -func DurationToDurationField(duration time.Duration) (key string, value interface{}) -``` -DurationToDurationField uses the duration value to log the request duration. - -## func [DurationToTimeMillisField](./options.go#L174) -``` go -func DurationToTimeMillisField(duration time.Duration) (key string, value interface{}) -``` -DurationToTimeMillisField converts the duration to milliseconds and uses the key `grpc.time_ms`. - -## func [Extract](./context.go#L17) -``` go -func Extract(ctx context.Context) *logrus.Entry -``` -Extract takes the call-scoped logrus.Entry from grpc_logrus middleware. -Deprecated: should use the ctxlogrus.Extract instead - -#### Example: - -
-Click to expand code. - -```go -_ = func(ctx context.Context, ping *pb_testproto.PingRequest) (*pb_testproto.PingResponse, error) { - // Add fields the ctxtags of the request which will be added to all extracted loggers. - grpc_ctxtags.Extract(ctx).Set("custom_tags.string", "something").Set("custom_tags.int", 1337) - // Extract a single request-scoped logrus.Logger and log messages. - l := ctx_logrus.Extract(ctx) - l.Info("some ping") - l.Info("another ping") - return &pb_testproto.PingResponse{Value: ping.Value}, nil -} -``` - -
- -## func [PayloadStreamClientInterceptor](./payload_interceptors.go#L74) -``` go -func PayloadStreamClientInterceptor(entry *logrus.Entry, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor -``` -PayloadStreamClientInterceptor returns a new streaming client interceptor that logs the paylods of requests and responses. - -## func [PayloadStreamServerInterceptor](./payload_interceptors.go#L45) -``` go -func PayloadStreamServerInterceptor(entry *logrus.Entry, decider grpc_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor -``` -PayloadStreamServerInterceptor returns a new server server interceptors that logs the payloads of requests. - -This *only* works when placed *after* the `grpc_logrus.StreamServerInterceptor`. However, the logging can be done to a -separate instance of the logger. - -## func [PayloadUnaryClientInterceptor](./payload_interceptors.go#L58) -``` go -func PayloadUnaryClientInterceptor(entry *logrus.Entry, decider grpc_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor -``` -PayloadUnaryClientInterceptor returns a new unary client interceptor that logs the paylods of requests and responses. - -## func [PayloadUnaryServerInterceptor](./payload_interceptors.go#L25) -``` go -func PayloadUnaryServerInterceptor(entry *logrus.Entry, decider grpc_logging.ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor -``` -PayloadUnaryServerInterceptor returns a new unary server interceptors that logs the payloads of requests. - -This *only* works when placed *after* the `grpc_logrus.UnaryServerInterceptor`. However, the logging can be done to a -separate instance of the logger. - -## func [ReplaceGrpcLogger](./grpclogger.go#L13) -``` go -func ReplaceGrpcLogger(logger *logrus.Entry) -``` -ReplaceGrpcLogger sets the given logrus.Logger as a gRPC-level logger. -This should be called *before* any other initialization, preferably from init() functions. - -## func [StreamClientInterceptor](./client_interceptors.go#L28) -``` go -func StreamClientInterceptor(entry *logrus.Entry, opts ...Option) grpc.StreamClientInterceptor -``` -StreamServerInterceptor returns a new streaming client interceptor that optionally logs the execution of external gRPC calls. - -## func [StreamServerInterceptor](./server_interceptors.go#L58) -``` go -func StreamServerInterceptor(entry *logrus.Entry, opts ...Option) grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor that adds logrus.Entry to the context. - -## func [UnaryClientInterceptor](./client_interceptors.go#L16) -``` go -func UnaryClientInterceptor(entry *logrus.Entry, opts ...Option) grpc.UnaryClientInterceptor -``` -UnaryClientInterceptor returns a new unary client interceptor that optionally logs the execution of external gRPC calls. - -## func [UnaryServerInterceptor](./server_interceptors.go#L26) -``` go -func UnaryServerInterceptor(entry *logrus.Entry, opts ...Option) grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptors that adds logrus.Entry to the context. - -## type [CodeToLevel](./options.go#L53) -``` go -type CodeToLevel func(code codes.Code) logrus.Level -``` -CodeToLevel function defines the mapping between gRPC return codes and interceptor log level. - -## type [DurationToField](./options.go#L56) -``` go -type DurationToField func(duration time.Duration) (key string, value interface{}) -``` -DurationToField function defines how to produce duration fields for logging - -## type [Option](./options.go#L50) -``` go -type Option func(*options) -``` - -### func [WithCodes](./options.go#L73) -``` go -func WithCodes(f grpc_logging.ErrorToCode) Option -``` -WithCodes customizes the function for mapping errors to error codes. - -### func [WithDecider](./options.go#L59) -``` go -func WithDecider(f grpc_logging.Decider) Option -``` -WithDecider customizes the function for deciding if the gRPC interceptor logs should log. - -#### Example: - -
-Click to expand code. - -```go -opts := []grpc_logrus.Option{ - grpc_logrus.WithDecider(func(methodFullName string, err error) bool { - // will not log gRPC calls if it was a call to healthcheck and no error was raised - if err == nil && methodFullName == "blah.foo.healthcheck" { - return false - } - - // by default you will log all calls - return true - }), -} - -_ = []grpc.ServerOption{ - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(), - grpc_logrus.StreamServerInterceptor(logrus.NewEntry(logrus.New()), opts...)), - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(), - grpc_logrus.UnaryServerInterceptor(logrus.NewEntry(logrus.New()), opts...)), -} -``` - -
-### func [WithDurationField](./options.go#L80) -``` go -func WithDurationField(f DurationToField) Option -``` -WithDurationField customizes the function for mapping request durations to log fields. - -### func [WithLevels](./options.go#L66) -``` go -func WithLevels(f CodeToLevel) Option -``` -WithLevels customizes the function for mapping gRPC return codes and interceptor log level statements. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/logging/logrus/README.md b/logging/logrus/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/logging/logrus/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/logging/logrus/ctxlogrus/DOC.md b/logging/logrus/ctxlogrus/DOC.md deleted file mode 100644 index 909180292..000000000 --- a/logging/logrus/ctxlogrus/DOC.md +++ /dev/null @@ -1,93 +0,0 @@ -# ctxlogrus -`import "github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/ctxlogrus"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`ctxlogrus` is a ctxlogger that is backed by logrus - -It accepts a user-configured `logrus.Logger` that will be used for logging. The same `logrus.Logger` will -be populated into the `context.Context` passed into gRPC handler code. - -You can use `ctx_logrus.Extract` to log into a request-scoped `logrus.Logger` instance in your handler code. - -As `ctx_logrus.Extract` will iterate all tags on from `grpc_ctxtags` it is therefore expensive so it is advised that you -extract once at the start of the function from the context and reuse it for the remainder of the function (see examples). - -Please see examples and tests for examples of use. - -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware/tags](./../../../tags) -- [github.com/sirupsen/logrus](https://godoc.org/github.com/sirupsen/logrus) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) - -## Index -* [func AddFields(ctx context.Context, fields logrus.Fields)](#AddFields) -* [func Extract(ctx context.Context) \*logrus.Entry](#Extract) -* [func ToContext(ctx context.Context, entry \*logrus.Entry) context.Context](#ToContext) - -#### Examples -* [Extract (Unary)](#example_Extract_unary) - -#### Package files -[context.go](./context.go) [doc.go](./doc.go) [noop.go](./noop.go) - -## func [AddFields](./context.go#L21) -``` go -func AddFields(ctx context.Context, fields logrus.Fields) -``` -AddFields adds logrus fields to the logger. - -## func [Extract](./context.go#L35) -``` go -func Extract(ctx context.Context) *logrus.Entry -``` -Extract takes the call-scoped logrus.Entry from ctx_logrus middleware. - -If the ctx_logrus middleware wasn't used, a no-op `logrus.Entry` is returned. This makes it safe to -use regardless. - -#### Example: - -
-Click to expand code. - -```go -package ctxlogrus_test - -import ( - "github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/ctxlogrus" - "github.com/grpc-ecosystem/go-grpc-middleware/tags" - "github.com/sirupsen/logrus" - "golang.org/x/net/context" -) - -var logrusLogger *logrus.Logger - -// Simple unary handler that adds custom fields to the requests's context. These will be used for all log statements. -func ExampleExtract_unary() { - ctx := context.Background() - // setting tags will be added to the logger as log fields - grpc_ctxtags.Extract(ctx).Set("custom_tags.string", "something").Set("custom_tags.int", 1337) - // Extract a single request-scoped logrus.Logger and log messages. - l := ctxlogrus.Extract(ctx) - l.Info("some ping") - l.Info("another ping") -} -``` - -
- -## func [ToContext](./context.go#L59) -``` go -func ToContext(ctx context.Context, entry *logrus.Entry) context.Context -``` -ToContext adds the logrus.Entry to the context for extraction later. -Returning the new context that has been created. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/logging/logrus/ctxlogrus/README.md b/logging/logrus/ctxlogrus/README.md deleted file mode 100644 index fc1d0a922..000000000 --- a/logging/logrus/ctxlogrus/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# ctx_logrus -`import "github.com/grpc-ecosystem/go-grpc-middleware/tags/logrus"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## Overview -`ctx_logrus` is a ctxlogger that is backed by logrus - -It accepts a user-configured `logrus.Logger` that will be used for logging. The same `logrus.Logger` will -be populated into the `context.Context` passed into gRPC handler code. - -You can use `ctx_logrus.Extract` to log into a request-scoped `logrus.Logger` instance in your handler code. - -As `ctx_logrus.Extract` will iterate all tags on from `grpc_ctxtags` it is therefore expensive so it is advised that you -extract once at the start of the function from the context and reuse it for the remainder of the function (see examples). - -Please see examples and tests for examples of use. - -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware/tags](./..) -- [github.com/sirupsen/logrus](https://godoc.org/github.com/sirupsen/logrus) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) - -## Index -* [func AddFields(ctx context.Context, fields logrus.Fields)](#AddFields) -* [func Extract(ctx context.Context) \*logrus.Entry](#Extract) -* [func ToContext(ctx context.Context, entry \*logrus.Entry) context.Context](#ToContext) - -#### Package files -[context.go](./context.go) [doc.go](./doc.go) [noop.go](./noop.go) - -## func [AddFields](./context.go#L21) -``` go -func AddFields(ctx context.Context, fields logrus.Fields) -``` -AddFields adds logrus fields to the logger. - -## func [Extract](./context.go#L35) -``` go -func Extract(ctx context.Context) *logrus.Entry -``` -Extract takes the call-scoped logrus.Entry from ctx_logrus middleware. - -If the ctx_logrus middleware wasn't used, a no-op `logrus.Entry` is returned. This makes it safe to -use regardless. - -## func [ToContext](./context.go#L59) -``` go -func ToContext(ctx context.Context, entry *logrus.Entry) context.Context -``` -ToContext adds the logrus.Entry to the context for extraction later. -Returning the new context that has been created. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/logging/zap/DOC.md b/logging/zap/DOC.md deleted file mode 100644 index e1c5630a1..000000000 --- a/logging/zap/DOC.md +++ /dev/null @@ -1,402 +0,0 @@ -# grpc_zap -`import "github.com/grpc-ecosystem/go-grpc-middleware/logging/zap"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`grpc_zap` is a gRPC logging middleware backed by ZAP loggers - -It accepts a user-configured `zap.Logger` that will be used for logging completed gRPC calls. The same `zap.Logger` will -be used for logging completed gRPC calls, and be populated into the `context.Context` passed into gRPC handler code. - -On calling `StreamServerInterceptor` or `UnaryServerInterceptor` this logging middleware will add gRPC call information -to the ctx so that it will be present on subsequent use of the `ctx_zap` logger. - -If a deadline is present on the gRPC request the grpc.request.deadline tag is populated when the request begins. grpc.request.deadline -is a string representing the time (RFC3339) when the current call will expire. - -This package also implements request and response *payload* logging, both for server-side and client-side. These will be -logged as structured `jsonpb` fields for every message received/sent (both unary and streaming). For that please use -`Payload*Interceptor` functions for that. Please note that the user-provided function that determines whetether to log -the full request/response payload needs to be written with care, this can significantly slow down gRPC. - -ZAP can also be made as a backend for gRPC library internals. For that use `ReplaceGrpcLogger`. - -*Server Interceptor* -Below is a JSON formatted example of a log that would be logged by the server interceptor: - - { - "level": "info", // string zap log levels - "msg": "finished unary call", // string log message - - "grpc.code": "OK", // string grpc status code - "grpc.method": "Ping", // string method name - "grpc.service": "mwitkow.testproto.TestService", // string full name of the called service - "grpc.start_time": "2006-01-02T15:04:05Z07:00", // string RFC3339 representation of the start time - "grpc.request.deadline": "2006-01-02T15:04:05Z07:00", // string RFC3339 deadline of the current request if supplied - "grpc.request.value": "something", // string value on the request - "grpc.time_ms": 1.345, // float32 run time of the call in ms - - "peer.address": { - "IP": "127.0.0.1", // string IP address of calling party - "Port": 60216, // int port call is coming in on - "Zone": "" // string peer zone for caller - }, - "span.kind": "server", // string client | server - "system": "grpc" // string - - "custom_field": "custom_value", // string user defined field - "custom_tags.int": 1337, // int user defined tag on the ctx - "custom_tags.string": "something", // string user defined tag on the ctx - } - -*Payload Interceptor* -Below is a JSON formatted example of a log that would be logged by the payload interceptor: - - { - "level": "info", // string zap log levels - "msg": "client request payload logged as grpc.request.content", // string log message - - "grpc.request.content": { // object content of RPC request - "msg" : { // object ZAP specific inner object - "value": "something", // string defined by caller - "sleepTimeMs": 9999 // int defined by caller - } - }, - "grpc.method": "Ping", // string method being called - "grpc.service": "mwitkow.testproto.TestService", // string service being called - - "span.kind": "client", // string client | server - "system": "grpc" // string - } - -Note - due to implementation ZAP differs from Logrus in the "grpc.request.content" object by having an inner "msg" object. - -Please see examples and tests for examples of use. - -#### Example: - -
-Click to expand code. - -```go -// Shared options for the logger, with a custom gRPC code to log level function. -opts := []grpc_zap.Option{ - grpc_zap.WithLevels(customFunc), -} -// Make sure that log statements internal to gRPC library are logged using the zapLogger as well. -grpc_zap.ReplaceGrpcLogger(zapLogger) -// Create a server, make sure we put the grpc_ctxtags context before everything else. -_ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), - grpc_zap.UnaryServerInterceptor(zapLogger, opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), - grpc_zap.StreamServerInterceptor(zapLogger, opts...), - ), -) -``` - -
- -#### Example: - -
-Click to expand code. - -```go -opts := []grpc_zap.Option{ - grpc_zap.WithDecider(func(fullMethodName string, err error) bool { - // will not log gRPC calls if it was a call to healthcheck and no error was raised - if err == nil && fullMethodName == "foo.bar.healthcheck" { - return false - } - - // by default everything will be logged - return true - }), -} - -_ = []grpc.ServerOption{ - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(), - grpc_zap.StreamServerInterceptor(zap.NewNop(), opts...)), - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(), - grpc_zap.UnaryServerInterceptor(zap.NewNop(), opts...)), -} -``` - -
- -#### Example: - -
-Click to expand code. - -```go -opts := []grpc_zap.Option{ - grpc_zap.WithDurationField(func(duration time.Duration) zapcore.Field { - return zap.Int64("grpc.time_ns", duration.Nanoseconds()) - }), -} - -_ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(), - grpc_zap.UnaryServerInterceptor(zapLogger, opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(), - grpc_zap.StreamServerInterceptor(zapLogger, opts...), - ), -) -``` - -
- -## Imported Packages - -- [github.com/golang/protobuf/jsonpb](https://godoc.org/github.com/golang/protobuf/jsonpb) -- [github.com/golang/protobuf/proto](https://godoc.org/github.com/golang/protobuf/proto) -- [github.com/grpc-ecosystem/go-grpc-middleware](./../..) -- [github.com/grpc-ecosystem/go-grpc-middleware/logging](./..) -- [github.com/grpc-ecosystem/go-grpc-middleware/logging/zap/ctxzap](./ctxzap) -- [github.com/grpc-ecosystem/go-grpc-middleware/tags/zap](./../../tags/zap) -- [go.uber.org/zap](https://godoc.org/go.uber.org/zap) -- [go.uber.org/zap/zapcore](https://godoc.org/go.uber.org/zap/zapcore) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) -- [google.golang.org/grpc/grpclog](https://godoc.org/google.golang.org/grpc/grpclog) - -## Index -* [Variables](#pkg-variables) -* [func AddFields(ctx context.Context, fields ...zapcore.Field)](#AddFields) -* [func DefaultClientCodeToLevel(code codes.Code) zapcore.Level](#DefaultClientCodeToLevel) -* [func DefaultCodeToLevel(code codes.Code) zapcore.Level](#DefaultCodeToLevel) -* [func DurationToDurationField(duration time.Duration) zapcore.Field](#DurationToDurationField) -* [func DurationToTimeMillisField(duration time.Duration) zapcore.Field](#DurationToTimeMillisField) -* [func Extract(ctx context.Context) \*zap.Logger](#Extract) -* [func PayloadStreamClientInterceptor(logger \*zap.Logger, decider grpc\_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor](#PayloadStreamClientInterceptor) -* [func PayloadStreamServerInterceptor(logger \*zap.Logger, decider grpc\_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor](#PayloadStreamServerInterceptor) -* [func PayloadUnaryClientInterceptor(logger \*zap.Logger, decider grpc\_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor](#PayloadUnaryClientInterceptor) -* [func PayloadUnaryServerInterceptor(logger \*zap.Logger, decider grpc\_logging.ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor](#PayloadUnaryServerInterceptor) -* [func ReplaceGrpcLogger(logger \*zap.Logger)](#ReplaceGrpcLogger) -* [func StreamClientInterceptor(logger \*zap.Logger, opts ...Option) grpc.StreamClientInterceptor](#StreamClientInterceptor) -* [func StreamServerInterceptor(logger \*zap.Logger, opts ...Option) grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryClientInterceptor(logger \*zap.Logger, opts ...Option) grpc.UnaryClientInterceptor](#UnaryClientInterceptor) -* [func UnaryServerInterceptor(logger \*zap.Logger, opts ...Option) grpc.UnaryServerInterceptor](#UnaryServerInterceptor) -* [type CodeToLevel](#CodeToLevel) -* [type DurationToField](#DurationToField) -* [type Option](#Option) - * [func WithCodes(f grpc\_logging.ErrorToCode) Option](#WithCodes) - * [func WithDecider(f grpc\_logging.Decider) Option](#WithDecider) - * [func WithDurationField(f DurationToField) Option](#WithDurationField) - * [func WithLevels(f CodeToLevel) Option](#WithLevels) - -#### Examples -* [Extract (Unary)](#example_Extract_unary) -* [Package (Initialization)](#example__initialization) -* [Package (InitializationWithDecider)](#example__initializationWithDecider) -* [Package (InitializationWithDurationFieldOverride)](#example__initializationWithDurationFieldOverride) - -#### Package files -[client_interceptors.go](./client_interceptors.go) [context.go](./context.go) [doc.go](./doc.go) [grpclogger.go](./grpclogger.go) [options.go](./options.go) [payload_interceptors.go](./payload_interceptors.go) [server_interceptors.go](./server_interceptors.go) - -## Variables -``` go -var ( - // SystemField is used in every log statement made through grpc_zap. Can be overwritten before any initialization code. - SystemField = zap.String("system", "grpc") - - // ServerField is used in every server-side log statement made through grpc_zap.Can be overwritten before initialization. - ServerField = zap.String("span.kind", "server") -) -``` -``` go -var ( - // ClientField is used in every client-side log statement made through grpc_zap. Can be overwritten before initialization. - ClientField = zap.String("span.kind", "client") -) -``` -``` go -var DefaultDurationToField = DurationToTimeMillisField -``` -DefaultDurationToField is the default implementation of converting request duration to a Zap field. - -``` go -var ( - // JsonPbMarshaller is the marshaller used for serializing protobuf messages. - JsonPbMarshaller = &jsonpb.Marshaler{} -) -``` - -## func [AddFields](./context.go#L12) -``` go -func AddFields(ctx context.Context, fields ...zapcore.Field) -``` -AddFields adds zap fields to the logger. -Deprecated: should use the ctxzap.AddFields instead - -## func [DefaultClientCodeToLevel](./options.go#L127) -``` go -func DefaultClientCodeToLevel(code codes.Code) zapcore.Level -``` -DefaultClientCodeToLevel is the default implementation of gRPC return codes to log levels for client side. - -## func [DefaultCodeToLevel](./options.go#L85) -``` go -func DefaultCodeToLevel(code codes.Code) zapcore.Level -``` -DefaultCodeToLevel is the default implementation of gRPC return codes and interceptor log level for server side. - -## func [DurationToDurationField](./options.go#L178) -``` go -func DurationToDurationField(duration time.Duration) zapcore.Field -``` -DurationToDurationField uses a Duration field to log the request duration -and leaves it up to Zap's encoder settings to determine how that is output. - -## func [DurationToTimeMillisField](./options.go#L172) -``` go -func DurationToTimeMillisField(duration time.Duration) zapcore.Field -``` -DurationToTimeMillisField converts the duration to milliseconds and uses the key `grpc.time_ms`. - -## func [Extract](./context.go#L18) -``` go -func Extract(ctx context.Context) *zap.Logger -``` -Extract takes the call-scoped Logger from grpc_zap middleware. -Deprecated: should use the ctxzap.Extract instead - -#### Example: - -
-Click to expand code. - -```go -_ = func(ctx context.Context, ping *pb_testproto.PingRequest) (*pb_testproto.PingResponse, error) { - // Add fields the ctxtags of the request which will be added to all extracted loggers. - grpc_ctxtags.Extract(ctx).Set("custom_tags.string", "something").Set("custom_tags.int", 1337) - - // Extract a single request-scoped zap.Logger and log messages. (containing the grpc.xxx tags) - l := ctx_zap.Extract(ctx) - l.Info("some ping") - l.Info("another ping") - return &pb_testproto.PingResponse{Value: ping.Value}, nil -} -``` - -
- -## func [PayloadStreamClientInterceptor](./payload_interceptors.go#L74) -``` go -func PayloadStreamClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor -``` -PayloadStreamClientInterceptor returns a new streaming client interceptor that logs the paylods of requests and responses. - -## func [PayloadStreamServerInterceptor](./payload_interceptors.go#L46) -``` go -func PayloadStreamServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor -``` -PayloadStreamServerInterceptor returns a new server server interceptors that logs the payloads of requests. - -This *only* works when placed *after* the `grpc_zap.StreamServerInterceptor`. However, the logging can be done to a -separate instance of the logger. - -## func [PayloadUnaryClientInterceptor](./payload_interceptors.go#L58) -``` go -func PayloadUnaryClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor -``` -PayloadUnaryClientInterceptor returns a new unary client interceptor that logs the paylods of requests and responses. - -## func [PayloadUnaryServerInterceptor](./payload_interceptors.go#L26) -``` go -func PayloadUnaryServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor -``` -PayloadUnaryServerInterceptor returns a new unary server interceptors that logs the payloads of requests. - -This *only* works when placed *after* the `grpc_zap.UnaryServerInterceptor`. However, the logging can be done to a -separate instance of the logger. - -## func [ReplaceGrpcLogger](./grpclogger.go#L15) -``` go -func ReplaceGrpcLogger(logger *zap.Logger) -``` -ReplaceGrpcLogger sets the given zap.Logger as a gRPC-level logger. -This should be called *before* any other initialization, preferably from init() functions. - -## func [StreamClientInterceptor](./client_interceptors.go#L34) -``` go -func StreamClientInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamClientInterceptor -``` -StreamClientInterceptor returns a new streaming client interceptor that optionally logs the execution of external gRPC calls. - -## func [StreamServerInterceptor](./server_interceptors.go#L51) -``` go -func StreamServerInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor that adds zap.Logger to the context. - -## func [UnaryClientInterceptor](./client_interceptors.go#L22) -``` go -func UnaryClientInterceptor(logger *zap.Logger, opts ...Option) grpc.UnaryClientInterceptor -``` -UnaryClientInterceptor returns a new unary client interceptor that optionally logs the execution of external gRPC calls. - -## func [UnaryServerInterceptor](./server_interceptors.go#L25) -``` go -func UnaryServerInterceptor(logger *zap.Logger, opts ...Option) grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptors that adds zap.Logger to the context. - -## type [CodeToLevel](./options.go#L51) -``` go -type CodeToLevel func(code codes.Code) zapcore.Level -``` -CodeToLevel function defines the mapping between gRPC return codes and interceptor log level. - -## type [DurationToField](./options.go#L54) -``` go -type DurationToField func(duration time.Duration) zapcore.Field -``` -DurationToField function defines how to produce duration fields for logging - -## type [Option](./options.go#L48) -``` go -type Option func(*options) -``` - -### func [WithCodes](./options.go#L71) -``` go -func WithCodes(f grpc_logging.ErrorToCode) Option -``` -WithCodes customizes the function for mapping errors to error codes. - -### func [WithDecider](./options.go#L57) -``` go -func WithDecider(f grpc_logging.Decider) Option -``` -WithDecider customizes the function for deciding if the gRPC interceptor logs should log. - -### func [WithDurationField](./options.go#L78) -``` go -func WithDurationField(f DurationToField) Option -``` -WithDurationField customizes the function for mapping request durations to Zap fields. - -### func [WithLevels](./options.go#L64) -``` go -func WithLevels(f CodeToLevel) Option -``` -WithLevels customizes the function for mapping gRPC return codes and interceptor log level statements. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/logging/zap/README.md b/logging/zap/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/logging/zap/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/logging/zap/ctxzap/DOC.md b/logging/zap/ctxzap/DOC.md deleted file mode 100644 index bfe4e7880..000000000 --- a/logging/zap/ctxzap/DOC.md +++ /dev/null @@ -1,105 +0,0 @@ -# ctxzap -`import "github.com/grpc-ecosystem/go-grpc-middleware/logging/zap/ctxzap"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`ctxzap` is a ctxlogger that is backed by Zap - -It accepts a user-configured `zap.Logger` that will be used for logging. The same `zap.Logger` will -be populated into the `context.Context` passed into gRPC handler code. - -You can use `ctxzap.Extract` to log into a request-scoped `zap.Logger` instance in your handler code. - -As `ctxzap.Extract` will iterate all tags on from `grpc_ctxtags` it is therefore expensive so it is advised that you -extract once at the start of the function from the context and reuse it for the remainder of the function (see examples). - -Please see examples and tests for examples of use. - -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware/tags](./../../../tags) -- [go.uber.org/zap](https://godoc.org/go.uber.org/zap) -- [go.uber.org/zap/zapcore](https://godoc.org/go.uber.org/zap/zapcore) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) - -## Index -* [func AddFields(ctx context.Context, fields ...zapcore.Field)](#AddFields) -* [func Extract(ctx context.Context) \*zap.Logger](#Extract) -* [func TagsToFields(ctx context.Context) []zapcore.Field](#TagsToFields) -* [func ToContext(ctx context.Context, logger \*zap.Logger) context.Context](#ToContext) - -#### Examples -* [Extract (Unary)](#example_Extract_unary) - -#### Package files -[context.go](./context.go) [doc.go](./doc.go) - -## func [AddFields](./context.go#L23) -``` go -func AddFields(ctx context.Context, fields ...zapcore.Field) -``` -AddFields adds zap fields to the logger. - -## func [Extract](./context.go#L35) -``` go -func Extract(ctx context.Context) *zap.Logger -``` -Extract takes the call-scoped Logger from grpc_zap middleware. - -It always returns a Logger that has all the grpc_ctxtags updated. - -#### Example: - -
-Click to expand code. - -```go -package ctxzap_test - -import ( - "context" - - "github.com/grpc-ecosystem/go-grpc-middleware/logging/zap/ctxzap" - "github.com/grpc-ecosystem/go-grpc-middleware/tags" - pb_testproto "github.com/grpc-ecosystem/go-grpc-middleware/testing/testproto" - "go.uber.org/zap" -) - -var zapLogger *zap.Logger - -// Simple unary handler that adds custom fields to the requests's context. These will be used for all log statements. -func ExampleExtract_unary() { - _ = func(ctx context.Context, ping *pb_testproto.PingRequest) (*pb_testproto.PingResponse, error) { - // Add fields the ctxtags of the request which will be added to all extracted loggers. - grpc_ctxtags.Extract(ctx).Set("custom_tags.string", "something").Set("custom_tags.int", 1337) - - // Extract a single request-scoped zap.Logger and log messages. - l := ctxzap.Extract(ctx) - l.Info("some ping") - l.Info("another ping") - return &pb_testproto.PingResponse{Value: ping.Value}, nil - } -} -``` - -
- -## func [TagsToFields](./context.go#L48) -``` go -func TagsToFields(ctx context.Context) []zapcore.Field -``` -TagsToFields transforms the Tags on the supplied context into zap fields. - -## func [ToContext](./context.go#L59) -``` go -func ToContext(ctx context.Context, logger *zap.Logger) context.Context -``` -ToContext adds the zap.Logger to the context for extraction later. -Returning the new context that has been created. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/logging/zap/ctxzap/README.md b/logging/zap/ctxzap/README.md deleted file mode 100644 index 3943ea605..000000000 --- a/logging/zap/ctxzap/README.md +++ /dev/null @@ -1,65 +0,0 @@ -# ctx_zap -`import "github.com/grpc-ecosystem/go-grpc-middleware/tags/zap"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## Overview -`ctx_zap` is a ctxlogger that is backed by Zap - -It accepts a user-configured `zap.Logger` that will be used for logging. The same `zap.Logger` will -be populated into the `context.Context` passed into gRPC handler code. - -You can use `ctx_zap.Extract` to log into a request-scoped `zap.Logger` instance in your handler code. - -As `ctx_zap.Extract` will iterate all tags on from `grpc_ctxtags` it is therefore expensive so it is advised that you -extract once at the start of the function from the context and reuse it for the remainder of the function (see examples). - -Please see examples and tests for examples of use. - -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware/tags](./..) -- [go.uber.org/zap](https://godoc.org/go.uber.org/zap) -- [go.uber.org/zap/zapcore](https://godoc.org/go.uber.org/zap/zapcore) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) - -## Index -* [func AddFields(ctx context.Context, fields ...zapcore.Field)](#AddFields) -* [func Extract(ctx context.Context) \*zap.Logger](#Extract) -* [func TagsToFields(ctx context.Context) []zapcore.Field](#TagsToFields) -* [func ToContext(ctx context.Context, logger \*zap.Logger) context.Context](#ToContext) - -#### Package files -[context.go](./context.go) [doc.go](./doc.go) - -## func [AddFields](./context.go#L23) -``` go -func AddFields(ctx context.Context, fields ...zapcore.Field) -``` -AddFields adds zap fields to the logger. - -## func [Extract](./context.go#L35) -``` go -func Extract(ctx context.Context) *zap.Logger -``` -Extract takes the call-scoped Logger from grpc_zap middleware. - -It always returns a Logger that has all the grpc_ctxtags updated. - -## func [TagsToFields](./context.go#L48) -``` go -func TagsToFields(ctx context.Context) []zapcore.Field -``` -TagsToFields transforms the Tags on the supplied context into zap fields. - -## func [ToContext](./context.go#L59) -``` go -func ToContext(ctx context.Context, logger *zap.Logger) context.Context -``` -ToContext adds the zap.Logger to the context for extraction later. -Returning the new context that has been created. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/makefile b/makefile index 3e0f296b6..51dc5b8f2 100644 --- a/makefile +++ b/makefile @@ -1,14 +1,8 @@ -SHELL="/bin/bash" +SHELL=/bin/bash GOFILES_NOVENDOR = $(shell go list ./... | grep -v /vendor/) -all: vet fmt docs test - -docs: - ./scripts/docs.sh generate - -checkdocs: - ./scripts/docs.sh check +all: vet fmt test fmt: go fmt $(GOFILES_NOVENDOR) @@ -19,4 +13,4 @@ vet: test: vet ./scripts/test_all.sh -.PHONY: all docs validate test +.PHONY: all test diff --git a/recovery/DOC.md b/recovery/DOC.md deleted file mode 100644 index d4ef78af5..000000000 --- a/recovery/DOC.md +++ /dev/null @@ -1,107 +0,0 @@ -# grpc_recovery -`import "github.com/grpc-ecosystem/go-grpc-middleware/recovery"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`grpc_recovery` are intereceptors that recover from gRPC handler panics. - -### Server Side Recovery Middleware -By default a panic will be converted into a gRPC error with `code.Internal`. - -Handling can be customised by providing an alternate recovery function. - -Please see examples for simple examples of use. - -#### Example: - -
-Click to expand code. - -```go -package grpc_recovery_test - -import ( - "github.com/grpc-ecosystem/go-grpc-middleware" - "github.com/grpc-ecosystem/go-grpc-middleware/recovery" - "google.golang.org/grpc" -) - -var ( - customFunc grpc_recovery.RecoveryHandlerFunc -) - -// Initialization shows an initialization sequence with a custom recovery handler func. -func Example_initialization() { - // Shared options for the logger, with a custom gRPC code to log level function. - opts := []grpc_recovery.Option{ - grpc_recovery.WithRecoveryHandler(customFunc), - } - // Create a server. Recovery handlers should typically be last in the chain so that other middleware - // (e.g. logging) can operate on the recovered state instead of being directly affected by any panic - _ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_recovery.UnaryServerInterceptor(opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_recovery.StreamServerInterceptor(opts...), - ), - ) -} -``` - -
- -## Imported Packages - -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) - -## Index -* [func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor](#UnaryServerInterceptor) -* [type Option](#Option) - * [func WithRecoveryHandler(f RecoveryHandlerFunc) Option](#WithRecoveryHandler) -* [type RecoveryHandlerFunc](#RecoveryHandlerFunc) - -#### Examples -* [Package (Initialization)](#example__initialization) - -#### Package files -[doc.go](./doc.go) [interceptors.go](./interceptors.go) [options.go](./options.go) - -## func [StreamServerInterceptor](./interceptors.go#L30) -``` go -func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor for panic recovery. - -## func [UnaryServerInterceptor](./interceptors.go#L16) -``` go -func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptor for panic recovery. - -## type [Option](./options.go#L25) -``` go -type Option func(*options) -``` - -### func [WithRecoveryHandler](./options.go#L28) -``` go -func WithRecoveryHandler(f RecoveryHandlerFunc) Option -``` -WithRecoveryHandler customizes the function for recovering from a panic. - -## type [RecoveryHandlerFunc](./interceptors.go#L13) -``` go -type RecoveryHandlerFunc func(p interface{}) (err error) -``` -RecoveryHandlerFunc is a function that recovers from the panic `p` by returning an `error`. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/recovery/README.md b/recovery/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/recovery/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/retry/DOC.md b/retry/DOC.md deleted file mode 100644 index ddda635d7..000000000 --- a/retry/DOC.md +++ /dev/null @@ -1,255 +0,0 @@ -# grpc_retry -`import "github.com/grpc-ecosystem/go-grpc-middleware/retry"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`grpc_retry` provides client-side request retry logic for gRPC. - -### Client-Side Request Retry Interceptor -It allows for automatic retry, inside the generated gRPC code of requests based on the gRPC status -of the reply. It supports unary (1:1), and server stream (1:n) requests. - -By default the interceptors *are disabled*, preventing accidental use of retries. You can easily -override the number of retries (setting them to more than 0) with a `grpc.ClientOption`, e.g.: - - myclient.Ping(ctx, goodPing, grpc_retry.WithMax(5)) - -Other default options are: retry on `ResourceExhausted` and `Unavailable` gRPC codes, use a 50ms -linear backoff with 10% jitter. - -For chained interceptors, the retry interceptor will call every interceptor that follows it -whenever when a retry happens. - -Please see examples for more advanced use. - -#### Example: - -
-Click to expand code. - -```go -grpc.Dial("myservice.example.com", - grpc.WithStreamInterceptor(grpc_retry.StreamClientInterceptor()), - grpc.WithUnaryInterceptor(grpc_retry.UnaryClientInterceptor()), -) -``` - -
- -#### Example: - -
-Click to expand code. - -```go -opts := []grpc_retry.CallOption{ - grpc_retry.WithBackoff(grpc_retry.BackoffLinear(100 * time.Millisecond)), - grpc_retry.WithCodes(codes.NotFound, codes.Aborted), -} -grpc.Dial("myservice.example.com", - grpc.WithStreamInterceptor(grpc_retry.StreamClientInterceptor(opts...)), - grpc.WithUnaryInterceptor(grpc_retry.UnaryClientInterceptor(opts...)), -) -``` - -
- -#### Example: - -
-Click to expand code. - -```go -client := pb_testproto.NewTestServiceClient(cc) -stream, _ := client.PingList(newCtx(1*time.Second), &pb_testproto.PingRequest{}, grpc_retry.WithMax(3)) - -for { - pong, err := stream.Recv() // retries happen here - if err == io.EOF { - break - } else if err != nil { - return - } - fmt.Printf("got pong: %v", pong) -} -``` - -
- -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware/util/backoffutils](./../util/backoffutils) -- [github.com/grpc-ecosystem/go-grpc-middleware/util/metautils](./../util/metautils) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [golang.org/x/net/trace](https://godoc.org/golang.org/x/net/trace) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) -- [google.golang.org/grpc/metadata](https://godoc.org/google.golang.org/grpc/metadata) - -## Index -* [Constants](#pkg-constants) -* [Variables](#pkg-variables) -* [func StreamClientInterceptor(optFuncs ...CallOption) grpc.StreamClientInterceptor](#StreamClientInterceptor) -* [func UnaryClientInterceptor(optFuncs ...CallOption) grpc.UnaryClientInterceptor](#UnaryClientInterceptor) -* [type BackoffFunc](#BackoffFunc) - * [func BackoffLinear(waitBetween time.Duration) BackoffFunc](#BackoffLinear) - * [func BackoffLinearWithJitter(waitBetween time.Duration, jitterFraction float64) BackoffFunc](#BackoffLinearWithJitter) -* [type CallOption](#CallOption) - * [func Disable() CallOption](#Disable) - * [func WithBackoff(bf BackoffFunc) CallOption](#WithBackoff) - * [func WithCodes(retryCodes ...codes.Code) CallOption](#WithCodes) - * [func WithMax(maxRetries uint) CallOption](#WithMax) - * [func WithPerRetryTimeout(timeout time.Duration) CallOption](#WithPerRetryTimeout) - -#### Examples -* [WithPerRetryTimeout](#example_WithPerRetryTimeout) -* [Package (Initialization)](#example__initialization) -* [Package (InitializationWithOptions)](#example__initializationWithOptions) -* [Package (SimpleCall)](#example__simpleCall) - -#### Package files -[backoff.go](./backoff.go) [doc.go](./doc.go) [options.go](./options.go) [retry.go](./retry.go) - -## Constants -``` go -const ( - AttemptMetadataKey = "x-retry-attempty" -) -``` - -## Variables -``` go -var ( - // DefaultRetriableCodes is a set of well known types gRPC codes that should be retri-able. - // - // `ResourceExhausted` means that the user quota, e.g. per-RPC limits, have been reached. - // `Unavailable` means that system is currently unavailable and the client should retry again. - DefaultRetriableCodes = []codes.Code{codes.ResourceExhausted, codes.Unavailable} -) -``` - -## func [StreamClientInterceptor](./retry.go#L76) -``` go -func StreamClientInterceptor(optFuncs ...CallOption) grpc.StreamClientInterceptor -``` -StreamClientInterceptor returns a new retrying stream client interceptor for server side streaming calls. - -The default configuration of the interceptor is to not retry *at all*. This behaviour can be -changed through options (e.g. WithMax) on creation of the interceptor or on call (through grpc.CallOptions). - -Retry logic is available *only for ServerStreams*, i.e. 1:n streams, as the internal logic needs -to buffer the messages sent by the client. If retry is enabled on any other streams (ClientStreams, -BidiStreams), the retry interceptor will fail the call. - -## func [UnaryClientInterceptor](./retry.go#L28) -``` go -func UnaryClientInterceptor(optFuncs ...CallOption) grpc.UnaryClientInterceptor -``` -UnaryClientInterceptor returns a new retrying unary client interceptor. - -The default configuration of the interceptor is to not retry *at all*. This behaviour can be -changed through options (e.g. WithMax) on creation of the interceptor or on call (through grpc.CallOptions). - -## type [BackoffFunc](./options.go#L35) -``` go -type BackoffFunc func(attempt uint) time.Duration -``` -BackoffFunc denotes a family of functions that control the backoff duration between call retries. - -They are called with an identifier of the attempt, and should return a time the system client should -hold off for. If the time returned is longer than the `context.Context.Deadline` of the request -the deadline of the request takes precedence and the wait will be interrupted before proceeding -with the next iteration. - -### func [BackoffLinear](./backoff.go#L13) -``` go -func BackoffLinear(waitBetween time.Duration) BackoffFunc -``` -BackoffLinear is very simple: it waits for a fixed period of time between calls. - -### func [BackoffLinearWithJitter](./backoff.go#L22) -``` go -func BackoffLinearWithJitter(waitBetween time.Duration, jitterFraction float64) BackoffFunc -``` -BackoffLinearWithJitter waits a set period of time, allowing for jitter (fractional adjustment). - -For example waitBetween=1s and jitter=0.10 can generate waits between 900ms and 1100ms. - -## type [CallOption](./options.go#L94-L97) -``` go -type CallOption struct { - grpc.EmptyCallOption // make sure we implement private after() and before() fields so we don't panic. - // contains filtered or unexported fields -} -``` -CallOption is a grpc.CallOption that is local to grpc_retry. - -### func [Disable](./options.go#L40) -``` go -func Disable() CallOption -``` -Disable disables the retry behaviour on this call, or this interceptor. - -Its semantically the same to `WithMax` - -### func [WithBackoff](./options.go#L52) -``` go -func WithBackoff(bf BackoffFunc) CallOption -``` -WithBackoff sets the `BackoffFunc `used to control time between retries. - -### func [WithCodes](./options.go#L63) -``` go -func WithCodes(retryCodes ...codes.Code) CallOption -``` -WithCodes sets which codes should be retried. - -Please *use with care*, as you may be retrying non-idempotend calls. - -You cannot automatically retry on Cancelled and Deadline, please use `WithPerRetryTimeout` for these. - -### func [WithMax](./options.go#L45) -``` go -func WithMax(maxRetries uint) CallOption -``` -WithMax sets the maximum number of retries on this call, or this interceptor. - -### func [WithPerRetryTimeout](./options.go#L79) -``` go -func WithPerRetryTimeout(timeout time.Duration) CallOption -``` -WithPerRetryTimeout sets the RPC timeout per call (including initial call) on this call, or this interceptor. - -The context.Deadline of the call takes precedence and sets the maximum time the whole invocation -will take, but WithPerRetryTimeout can be used to limit the RPC time per each call. - -For example, with context.Deadline = now + 10s, and WithPerRetryTimeout(3 * time.Seconds), each -of the retry calls (including the initial one) will have a deadline of now + 3s. - -A value of 0 disables the timeout overrides completely and returns to each retry call using the -parent `context.Deadline`. - -#### Example: - -
-Click to expand code. - -```go -client := pb_testproto.NewTestServiceClient(cc) -pong, _ := client.Ping( - newCtx(5*time.Second), - &pb_testproto.PingRequest{}, - grpc_retry.WithMax(3), - grpc_retry.WithPerRetryTimeout(1*time.Second)) - -fmt.Printf("got pong: %v", pong) -``` - -
- -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/retry/README.md b/retry/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/retry/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/scripts/docs.sh b/scripts/docs.sh deleted file mode 100755 index 01172da2c..000000000 --- a/scripts/docs.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/bin/bash -# Script that checks the code for errors. - -GOBIN=${GOBIN:="$GOPATH/bin"} - -function print_real_go_files { - grep --files-without-match 'DO NOT EDIT!' $(find . -iname '*.go') --exclude=./vendor/* -} - -function generate_markdown { - echo "Generating Github markdown" - oldpwd=$(pwd) - for i in $(find . -iname 'doc.go' -not -path "*vendor/*"); do - realdir=$(cd $(dirname ${i}) && pwd -P) - package=${realdir##${GOPATH}/src/} - echo "$package" - cd ${dir} - ${GOBIN}/godoc2ghmd -ex -file DOC.md ${package} - ln -s DOC.md README.md 2> /dev/null # can fail - cd ${oldpwd} - done; -} - -function generate { - go get github.com/devnev/godoc2ghmd - generate_markdown - echo "returning $?" -} - -function check { - generate - count=$(git diff --numstat | wc -l | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//') - echo $count - if [ "$count" = "0" ]; then - return 0 - else - echo "Your markdown docs seem to be out of sync with the package docs. Please run make and consult CONTRIBUTING.MD" - return 1 - fi -} - -"$@" \ No newline at end of file diff --git a/tags/DOC.md b/tags/DOC.md deleted file mode 100644 index 907a59fb8..000000000 --- a/tags/DOC.md +++ /dev/null @@ -1,182 +0,0 @@ -# grpc_ctxtags -`import "github.com/grpc-ecosystem/go-grpc-middleware/tags"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) -* [Examples](#pkg-examples) - -## Overview -`grpc_ctxtags` adds a Tag object to the context that can be used by other middleware to add context about a request. - -### Request Context Tags -Tags describe information about the request, and can be set and used by other middleware, or handlers. Tags are used -for logging and tracing of requests. Tags are populated both upwards, *and* downwards in the interceptor-handler stack. - -You can automatically extract tags (in `grpc.request.`) from request payloads. - -For unary and server-streaming methods, pass in the `WithFieldExtractor` option. For client-streams and bidirectional-streams, you can -use `WithFieldExtractorForInitialReq` which will extract the tags from the first message passed from client to server. -Note the tags will not be modified for subsequent requests, so this option only makes sense when the initial message -establishes the meta-data for the stream. - -If a user doesn't use the interceptors that initialize the `Tags` object, all operations following from an `Extract(ctx)` -will be no-ops. This is to ensure that code doesn't panic if the interceptors weren't used. - -Tags fields are typed, and shallow and should follow the OpenTracing semantics convention: -https://github.com/opentracing/specification/blob/master/semantic_conventions.md - -#### Example: - -
-Click to expand code. - -```go -opts := []grpc_ctxtags.Option{ - grpc_ctxtags.WithFieldExtractorForInitialReq(grpc_ctxtags.TagBasedRequestFieldExtractor("log_fields")), -} -_ = grpc.NewServer( - grpc.StreamInterceptor(grpc_ctxtags.StreamServerInterceptor(opts...)), - grpc.UnaryInterceptor(grpc_ctxtags.UnaryServerInterceptor(opts...)), -) -``` - -
- -#### Example: - -
-Click to expand code. - -```go -opts := []grpc_ctxtags.Option{ - grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.TagBasedRequestFieldExtractor("log_fields")), -} -_ = grpc.NewServer( - grpc.StreamInterceptor(grpc_ctxtags.StreamServerInterceptor(opts...)), - grpc.UnaryInterceptor(grpc_ctxtags.UnaryServerInterceptor(opts...)), -) -``` - -
- -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware](./..) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/peer](https://godoc.org/google.golang.org/grpc/peer) - -## Index -* [Variables](#pkg-variables) -* [func CodeGenRequestFieldExtractor(fullMethod string, req interface{}) map[string]interface{}](#CodeGenRequestFieldExtractor) -* [func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor](#UnaryServerInterceptor) -* [type Option](#Option) - * [func WithFieldExtractor(f RequestFieldExtractorFunc) Option](#WithFieldExtractor) - * [func WithFieldExtractorForInitialReq(f RequestFieldExtractorFunc) Option](#WithFieldExtractorForInitialReq) -* [type RequestFieldExtractorFunc](#RequestFieldExtractorFunc) - * [func TagBasedRequestFieldExtractor(tagName string) RequestFieldExtractorFunc](#TagBasedRequestFieldExtractor) -* [type Tags](#Tags) - * [func Extract(ctx context.Context) Tags](#Extract) - -#### Examples -* [Package (InitialisationWithOptions)](#example__initialisationWithOptions) -* [Package (Initialization)](#example__initialization) - -#### Package files -[context.go](./context.go) [doc.go](./doc.go) [fieldextractor.go](./fieldextractor.go) [interceptors.go](./interceptors.go) [options.go](./options.go) - -## Variables -``` go -var ( - - // NoopTags is a trivial, minimum overhead implementation of Tags for which all operations are no-ops. - NoopTags = &noopTags{} -) -``` - -## func [CodeGenRequestFieldExtractor](./fieldextractor.go#L23) -``` go -func CodeGenRequestFieldExtractor(fullMethod string, req interface{}) map[string]interface{} -``` -CodeGenRequestFieldExtractor is a function that relies on code-generated functions that export log fields from requests. -These are usually coming from a protoc-plugin that generates additional information based on custom field options. - -## func [StreamServerInterceptor](./interceptors.go#L26) -``` go -func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor that sets the values for request tags. - -## func [UnaryServerInterceptor](./interceptors.go#L14) -``` go -func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptors that sets the values for request tags. - -## type [Option](./options.go#L26) -``` go -type Option func(*options) -``` - -### func [WithFieldExtractor](./options.go#L30) -``` go -func WithFieldExtractor(f RequestFieldExtractorFunc) Option -``` -WithFieldExtractor customizes the function for extracting log fields from protobuf messages, for -unary and server-streamed methods only. - -### func [WithFieldExtractorForInitialReq](./options.go#L39) -``` go -func WithFieldExtractorForInitialReq(f RequestFieldExtractorFunc) Option -``` -WithFieldExtractorForInitialReq customizes the function for extracting log fields from protobuf messages, -for all unary and streaming methods. For client-streams and bidirectional-streams, the tags will be -extracted from the first message from the client. - -## type [RequestFieldExtractorFunc](./fieldextractor.go#L13) -``` go -type RequestFieldExtractorFunc func(fullMethod string, req interface{}) map[string]interface{} -``` -RequestFieldExtractorFunc is a user-provided function that extracts field information from a gRPC request. -It is called from tags middleware on arrival of unary request or a server-stream request. -Keys and values will be added to the context tags of the request. If there are no fields, you should return a nil. - -### func [TagBasedRequestFieldExtractor](./fieldextractor.go#L43) -``` go -func TagBasedRequestFieldExtractor(tagName string) RequestFieldExtractorFunc -``` -TagBasedRequestFieldExtractor is a function that relies on Go struct tags to export log fields from requests. -These are usually coming from a protoc-plugin, such as Gogo protobuf. - - message Metadata { - repeated string tags = 1 [ (gogoproto.moretags) = "log_field:\"meta_tags\"" ]; - } - -The tagName is configurable using the tagName variable. Here it would be "log_field". - -## type [Tags](./context.go#L19-L27) -``` go -type Tags interface { - // Set sets the given key in the metadata tags. - Set(key string, value interface{}) Tags - // Has checks if the given key exists. - Has(key string) bool - // Values returns a map of key to values. - // Do not modify the underlying map, please use Set instead. - Values() map[string]interface{} -} -``` -Tags is the interface used for storing request tags between Context calls. -The default implementation is *not* thread safe, and should be handled only in the context of the request. - -### func [Extract](./context.go#L63) -``` go -func Extract(ctx context.Context) Tags -``` -Extracts returns a pre-existing Tags object in the Context. -If the context wasn't set in a tag interceptor, a no-op Tag storage is returned that will *not* be propagated in context. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/tags/README.md b/tags/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/tags/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/tracing/opentracing/DOC.md b/tracing/opentracing/DOC.md deleted file mode 100644 index b8e1c2207..000000000 --- a/tracing/opentracing/DOC.md +++ /dev/null @@ -1,118 +0,0 @@ -# grpc_opentracing -`import "github.com/grpc-ecosystem/go-grpc-middleware/tracing/opentracing"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## Overview -`grpc_opentracing` adds OpenTracing - -### OpenTracing Interceptors -These are both client-side and server-side interceptors for OpenTracing. They are a provider-agnostic, with backends -such as Zipkin, or Google Stackdriver Trace. - -For a service that sends out requests and receives requests, you *need* to use both, otherwise downstream requests will -not have the appropriate requests propagated. - -All server-side spans are tagged with grpc_ctxtags information. - -For more information see: -http://opentracing.io/documentation/ -https://github.com/opentracing/specification/blob/master/semantic_conventions.md - -## Imported Packages - -- [github.com/grpc-ecosystem/go-grpc-middleware](./../..) -- [github.com/grpc-ecosystem/go-grpc-middleware/tags](./../../tags) -- [github.com/grpc-ecosystem/go-grpc-middleware/util/metautils](./../../util/metautils) -- [github.com/opentracing/opentracing-go](https://godoc.org/github.com/opentracing/opentracing-go) -- [github.com/opentracing/opentracing-go/ext](https://godoc.org/github.com/opentracing/opentracing-go/ext) -- [github.com/opentracing/opentracing-go/log](https://godoc.org/github.com/opentracing/opentracing-go/log) -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/grpclog](https://godoc.org/google.golang.org/grpc/grpclog) -- [google.golang.org/grpc/metadata](https://godoc.org/google.golang.org/grpc/metadata) - -## Index -* [Constants](#pkg-constants) -* [func ClientAddContextTags(ctx context.Context, tags opentracing.Tags) context.Context](#ClientAddContextTags) -* [func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor](#StreamClientInterceptor) -* [func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor](#UnaryClientInterceptor) -* [func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor](#UnaryServerInterceptor) -* [type FilterFunc](#FilterFunc) -* [type Option](#Option) - * [func WithFilterFunc(f FilterFunc) Option](#WithFilterFunc) - * [func WithTracer(tracer opentracing.Tracer) Option](#WithTracer) - -#### Package files -[client_interceptors.go](./client_interceptors.go) [doc.go](./doc.go) [id_extract.go](./id_extract.go) [metadata.go](./metadata.go) [options.go](./options.go) [server_interceptors.go](./server_interceptors.go) - -## Constants -``` go -const ( - TagTraceId = "trace.traceid" - TagSpanId = "trace.spanid" -) -``` - -## func [ClientAddContextTags](./client_interceptors.go#L105) -``` go -func ClientAddContextTags(ctx context.Context, tags opentracing.Tags) context.Context -``` -ClientAddContextTags returns a context with specified opentracing tags, which -are used by UnaryClientInterceptor/StreamClientInterceptor when creating a -new span. - -## func [StreamClientInterceptor](./client_interceptors.go#L35) -``` go -func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor -``` -StreamClientInterceptor returns a new streaming client interceptor for OpenTracing. - -## func [StreamServerInterceptor](./server_interceptors.go#L37) -``` go -func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor for OpenTracing. - -## func [UnaryClientInterceptor](./client_interceptors.go#L21) -``` go -func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor -``` -UnaryClientInterceptor returns a new unary client interceptor for OpenTracing. - -## func [UnaryServerInterceptor](./server_interceptors.go#L23) -``` go -func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptor for OpenTracing. - -## type [FilterFunc](./options.go#L22) -``` go -type FilterFunc func(ctx context.Context, fullMethodName string) bool -``` -FilterFunc allows users to provide a function that filters out certain methods from being traced. - -If it returns false, the given request will not be traced. - -## type [Option](./options.go#L41) -``` go -type Option func(*options) -``` - -### func [WithFilterFunc](./options.go#L44) -``` go -func WithFilterFunc(f FilterFunc) Option -``` -WithFilterFunc customizes the function used for deciding whether a given call is traced or not. - -### func [WithTracer](./options.go#L51) -``` go -func WithTracer(tracer opentracing.Tracer) Option -``` -WithTracer sets a custom tracer to be used for this middleware, otherwise the opentracing.GlobalTracer is used. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/tracing/opentracing/README.md b/tracing/opentracing/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/tracing/opentracing/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/util/metautils/DOC.md b/util/metautils/DOC.md deleted file mode 100644 index a02cde31e..000000000 --- a/util/metautils/DOC.md +++ /dev/null @@ -1,114 +0,0 @@ -# metautils -`import "github.com/grpc-ecosystem/go-grpc-middleware/util/metautils"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## Overview - -## Imported Packages - -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc/metadata](https://godoc.org/google.golang.org/grpc/metadata) - -## Index -* [type NiceMD](#NiceMD) - * [func ExtractIncoming(ctx context.Context) NiceMD](#ExtractIncoming) - * [func ExtractOutgoing(ctx context.Context) NiceMD](#ExtractOutgoing) - * [func (m NiceMD) Add(key string, value string) NiceMD](#NiceMD.Add) - * [func (m NiceMD) Clone(copiedKeys ...string) NiceMD](#NiceMD.Clone) - * [func (m NiceMD) Del(key string) NiceMD](#NiceMD.Del) - * [func (m NiceMD) Get(key string) string](#NiceMD.Get) - * [func (m NiceMD) Set(key string, value string) NiceMD](#NiceMD.Set) - * [func (m NiceMD) ToIncoming(ctx context.Context) context.Context](#NiceMD.ToIncoming) - * [func (m NiceMD) ToOutgoing(ctx context.Context) context.Context](#NiceMD.ToOutgoing) - -#### Package files -[doc.go](./doc.go) [nicemd.go](./nicemd.go) [single_key.go](./single_key.go) - -## type [NiceMD](./nicemd.go#L14) -``` go -type NiceMD metadata.MD -``` -NiceMD is a convenience wrapper definiting extra functions on the metadata. - -### func [ExtractIncoming](./nicemd.go#L20) -``` go -func ExtractIncoming(ctx context.Context) NiceMD -``` -ExtractIncoming extracts an inbound metadata from the server-side context. - -This function always returns a NiceMD wrapper of the metadata.MD, in case the context doesn't have metadata it returns -a new empty NiceMD. - -### func [ExtractOutgoing](./nicemd.go#L32) -``` go -func ExtractOutgoing(ctx context.Context) NiceMD -``` -ExtractOutgoing extracts an outbound metadata from the client-side context. - -This function always returns a NiceMD wrapper of the metadata.MD, in case the context doesn't have metadata it returns -a new empty NiceMD. - -### func (NiceMD) [Add](./nicemd.go#L122) -``` go -func (m NiceMD) Add(key string, value string) NiceMD -``` -Add retrieves a single value from the metadata. - -It works analogously to http.Header.Add, as it appends to any existing values associated with key. - -The function is binary-key safe. - -### func (NiceMD) [Clone](./nicemd.go#L44) -``` go -func (m NiceMD) Clone(copiedKeys ...string) NiceMD -``` -Clone performs a *deep* copy of the metadata.MD. - -You can specify the lower-case copiedKeys to only copy certain whitelisted keys. If no keys are explicitly whitelisted -all keys get copied. - -### func (NiceMD) [Del](./nicemd.go#L100) -``` go -func (m NiceMD) Del(key string) NiceMD -``` - -### func (NiceMD) [Get](./nicemd.go#L85) -``` go -func (m NiceMD) Get(key string) string -``` -Get retrieves a single value from the metadata. - -It works analogously to http.Header.Get, returning the first value if there are many set. If the value is not set, -an empty string is returned. - -The function is binary-key safe. - -### func (NiceMD) [Set](./nicemd.go#L111) -``` go -func (m NiceMD) Set(key string, value string) NiceMD -``` -Set sets the given value in a metadata. - -It works analogously to http.Header.Set, overwriting all previous metadata values. - -The function is binary-key safe. - -### func (NiceMD) [ToIncoming](./nicemd.go#L75) -``` go -func (m NiceMD) ToIncoming(ctx context.Context) context.Context -``` -ToIncoming sets the given NiceMD as a server-side context for dispatching. - -This is mostly useful in ServerInterceptors.. - -### func (NiceMD) [ToOutgoing](./nicemd.go#L68) -``` go -func (m NiceMD) ToOutgoing(ctx context.Context) context.Context -``` -ToOutgoing sets the given NiceMD as a client-side context for dispatching. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/util/metautils/README.md b/util/metautils/README.md deleted file mode 120000 index 71bfc07c9..000000000 --- a/util/metautils/README.md +++ /dev/null @@ -1 +0,0 @@ -DOC.md \ No newline at end of file diff --git a/validator/DOC.md b/validator/DOC.md deleted file mode 100644 index 4741bebf0..000000000 --- a/validator/DOC.md +++ /dev/null @@ -1,80 +0,0 @@ -# grpc_validator -`import "github.com/grpc-ecosystem/go-grpc-middleware/validator"` - -* [Overview](#pkg-overview) -* [Imported Packages](#pkg-imports) -* [Index](#pkg-index) - -## Overview -`grpc_validator` is a generic request contents validator server-side middleware for gRPC. - -### Request Validator Middleware -Validating input is important, and hard. It also causes a lot of boilerplate code. This middleware -checks for the existence of a `Validate` method on each of the messages of a gRPC request. This -includes the single request of the `Unary` calls, as well as each message of the inbound Stream calls. -In case of a validation failure, an `InvalidArgument` gRPC status is returned, along with a -description of the validation failure. - -While it is generic, it was intended to be used with https://github.com/mwitkow/go-proto-validators, -a Go protocol buffers codegen plugin that creates the `Validate` methods (including nested messages) -based on declarative options in the `.proto` files themselves. For example: - - syntax = "proto3"; - package validator.examples; - import "github.com/mwitkow/go-proto-validators/validator.proto"; - - message InnerMessage { - // some_integer can only be in range (1, 100). - int32 some_integer = 1 [(validator.field) = {int_gt: 0, int_lt: 100}]; - // some_float can only be in range (0;1). - double some_float = 2 [(validator.field) = {float_gte: 0, float_lte: 1}]; - } - - message OuterMessage { - // important_string must be a lowercase alpha-numeric of 5 to 30 characters (RE2 syntax). - string important_string = 1 [(validator.field) = {regex: "^[a-z]{2,5}$"}]; - // proto3 doesn't have `required`, the `msg_exist` enforces presence of InnerMessage. - InnerMessage inner = 2 [(validator.field) = {msg_exists : true}]; - } - -The `OuterMessage.Validate` would include validation of regexes, existence of the InnerMessage and -the range values within it. The `grpc_validator` middleware would then automatically use that to -check all messages processed by the server. - -Please consult https://github.com/mwitkow/go-proto-validators for details on `protoc` invocation and -other parameters of customization. - -## Imported Packages - -- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) -- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) -- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) - -## Index -* [func StreamServerInterceptor() grpc.StreamServerInterceptor](#StreamServerInterceptor) -* [func UnaryServerInterceptor() grpc.UnaryServerInterceptor](#UnaryServerInterceptor) - -#### Package files -[doc.go](./doc.go) [validator.go](./validator.go) - -## func [StreamServerInterceptor](./validator.go#L36) -``` go -func StreamServerInterceptor() grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor that validates incoming messages. - -The stage at which invalid messages will be rejected with `InvalidArgument` varies based on the -type of the RPC. For `ServerStream` (1:m) requests, it will happen before reaching any userspace -handlers. For `ClientStream` (n:1) or `BidiStream` (n:m) RPCs, the messages will be rejected on -calls to `stream.Recv()`. - -## func [UnaryServerInterceptor](./validator.go#L19) -``` go -func UnaryServerInterceptor() grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptor that validates incoming messages. - -Invalid messages will be rejected with `InvalidArgument` before reaching any userspace handlers. - -- - - -Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd) \ No newline at end of file diff --git a/validator/README.md b/validator/README.md deleted file mode 100644 index 8f95f38c3..000000000 --- a/validator/README.md +++ /dev/null @@ -1,73 +0,0 @@ -# grpc_validator - - import "github.com/grpc-ecosystem/go-grpc-middleware/validator" - -`grpc_validator` is a generic request contents validator server-side middleware for -gRPC. - - -### Request Validator Middleware - -Validating input is important, and hard. It also causes a lot of boilerplate code. -This middleware checks for the existence of a `Validate` method on each of the -messages of a gRPC request. This includes the single request of the `Unary` -calls, as well as each message of the inbound Stream calls. In case of a -validation failure, an `InvalidArgument` gRPC status is returned, along with -a description of the validation failure. - -While it is generic, it was intended to be used with -https://github.com/mwitkow/go-proto-validators, a Go protocol buffers codegen -plugin that creates the `Validate` methods (including nested messages) based on -declarative options in the `.proto` files themselves. For example: - - syntax = "proto3"; - package validator.examples; - import "github.com/mwitkow/go-proto-validators/validator.proto"; - - message InnerMessage { - // some_integer can only be in range (1, 100). - int32 some_integer = 1 [(validator.field) = {int_gt: 0, int_lt: 100}]; - // some_float can only be in range (0;1). - double some_float = 2 [(validator.field) = {float_gte: 0, float_lte: 1}]; - } - - message OuterMessage { - // important_string must be a lowercase alpha-numeric of 5 to 30 characters (RE2 syntax). - string important_string = 1 [(validator.field) = {regex: "^[a-z]{2,5}$"}]; - // proto3 doesn't have `required`, the `msg_exist` enforces presence of InnerMessage. - InnerMessage inner = 2 [(validator.field) = {msg_exists : true}]; - } - -The `OuterMessage.Validate` would include validation of regexes, existence of -the InnerMessage and the range values within it. The `grpc_validator` middleware -would then automatically use that to check all messages processed by the server. - -Please consult https://github.com/mwitkow/go-proto-validators for details on -`protoc` invocation and other parameters of customization. - -## Usage - -#### func StreamServerInterceptor - -```go -func StreamServerInterceptor() grpc.StreamServerInterceptor -``` -StreamServerInterceptor returns a new streaming server interceptor that -validates incoming messages. - -The stage at which invalid messages will be rejected with `InvalidArgument` -varies based on the type of the RPC. For `ServerStream` (1:m) requests, it will -happen before reaching any userspace handlers. For `ClientStream` (n:1) or -`BidiStream` (n:m) RPCs, the messages will be rejected on calls to -`stream.Recv()`. - -#### func UnaryServerInterceptor - -```go -func UnaryServerInterceptor() grpc.UnaryServerInterceptor -``` -UnaryServerInterceptor returns a new unary server interceptor that validates -incoming messages. - -Invalid messages will be rejected with `InvalidArgument` before reaching any -userspace handlers.