Skip to content

Commit

Permalink
Merge pull request #132 from domgreen/vet_fix
Browse files Browse the repository at this point in the history 
fixing vet issues ... most relating to the Examples
  • Loading branch information
@domgreen
domgreen authored Mar 1, 2018
2 parents f7cbcd2 + 5c44700 commit eb23b08
Show file tree
Hide file tree
Showing 16 changed files with 516 additions and 119 deletions.
57 changes: 57 additions & 0 deletions auth/DOC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
* [Overview](#pkg-overview)
* [Imported Packages](#pkg-imports)
* [Index](#pkg-index)
* [Examples](#pkg-examples)

## <a name="pkg-overview">Overview</a>
`grpc_auth` a generic server-side auth middleware for gRPC.
Expand All @@ -20,6 +21,59 @@ It also allows for per-service implementation overrides of `AuthFunc`. See `Serv

Please see examples for simple examples of use.

#### Example:

<details>
<summary>Click to expand code.</summary>

```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)),
)
}
```

</details>

## <a name="pkg-imports">Imported Packages</a>

- [github.com/grpc-ecosystem/go-grpc-middleware](./..)
Expand All @@ -35,6 +89,9 @@ Please see examples for simple examples of use.
* [type AuthFunc](#AuthFunc)
* [type ServiceAuthFuncOverride](#ServiceAuthFuncOverride)

#### <a name="pkg-examples">Examples</a>
* [Package (ServerConfig)](#example__serverConfig)

#### <a name="pkg-files">Package files</a>
[auth.go](./auth.go) [doc.go](./doc.go) [metadata.go](./metadata.go)

Expand Down
4 changes: 2 additions & 2 deletions auth/auth_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ func (s *AuthTestSuite) TestUnary_PassesAuth() {
}

func (s *AuthTestSuite) TestUnary_PassesWithPerRpcCredentials() {
grpcCreds := oauth.TokenSource{&fakeOAuth2TokenSource{accessToken: commonAuthToken}}
grpcCreds := oauth.TokenSource{TokenSource: &fakeOAuth2TokenSource{accessToken: commonAuthToken}}
client := s.NewClient(grpc.WithPerRPCCredentials(grpcCreds))
_, err := client.Ping(s.SimpleCtx(), goodPing)
require.NoError(s.T(), err, "no error must occur")
Expand Down Expand Up @@ -141,7 +141,7 @@ func (s *AuthTestSuite) TestStream_PassesAuth() {
}

func (s *AuthTestSuite) TestStream_PassesWithPerRpcCredentials() {
grpcCreds := oauth.TokenSource{&fakeOAuth2TokenSource{accessToken: commonAuthToken}}
grpcCreds := oauth.TokenSource{TokenSource: &fakeOAuth2TokenSource{accessToken: commonAuthToken}}
client := s.NewClient(grpc.WithPerRPCCredentials(grpcCreds))
stream, err := client.PingList(s.SimpleCtx(), goodPing)
require.NoError(s.T(), err, "should not fail on establishing the stream")
Expand Down
2 changes: 1 addition & 1 deletion auth/examples_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ func userClaimFromToken(struct{}) string {
}

// Simple example of server initialization code.
func Example_ServerConfig() {
func Example_serverConfig() {
exampleAuthFunc := func(ctx context.Context) (context.Context, error) {
token, err := grpc_auth.AuthFromMD(ctx, "bearer")
if err != nil {
Expand Down
136 changes: 106 additions & 30 deletions logging/logrus/DOC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ It accepts a user-configured `logrus.Entry` that will be used for logging comple
`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 `ctx_zap` logger.
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 `jsonbp` fields for every message received/sent (both unary and streaming). For that please use
Expand All @@ -29,52 +29,106 @@ Logrus can also be made as a backend for gRPC library internals. For that use `R
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" // 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

"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" // 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
"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
"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
"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
"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.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
"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:

<details>
<summary>Click to expand code.</summary>

```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...),
),
)
```

</details>

#### Example:

<details>
<summary>Click to expand code.</summary>

```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...),
),
)
```

</details>

## <a name="pkg-imports">Imported Packages</a>

- [github.com/golang/protobuf/jsonpb](https://godoc.org/github.com/golang/protobuf/jsonpb)
Expand Down Expand Up @@ -115,7 +169,10 @@ Please see examples and tests for examples of use.
* [func WithLevels(f CodeToLevel) Option](#WithLevels)

#### <a name="pkg-examples">Examples</a>
* [Extract (Unary)](#example_Extract_unary)
* [WithDecider](#example_WithDecider)
* [Package (Initialization)](#example__initialization)
* [Package (InitializationWithDurationFieldOverride)](#example__initializationWithDurationFieldOverride)

#### <a name="pkg-files">Package files</a>
[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)
Expand Down Expand Up @@ -180,6 +237,25 @@ 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:

<details>
<summary>Click to expand code.</summary>

```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
}
```

</details>

## <a name="PayloadStreamClientInterceptor">func</a> [PayloadStreamClientInterceptor](./payload_interceptors.go#L74)
``` go
func PayloadStreamClientInterceptor(entry *logrus.Entry, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor
Expand Down
35 changes: 35 additions & 0 deletions logging/logrus/ctxlogrus/DOC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
* [Overview](#pkg-overview)
* [Imported Packages](#pkg-imports)
* [Index](#pkg-index)
* [Examples](#pkg-examples)

## <a name="pkg-overview">Overview</a>
`ctxlogrus` is a ctxlogger that is backed by logrus
Expand All @@ -29,6 +30,9 @@ Please see examples and tests for examples of use.
* [func Extract(ctx context.Context) \*logrus.Entry](#Extract)
* [func ToContext(ctx context.Context, entry \*logrus.Entry) context.Context](#ToContext)

#### <a name="pkg-examples">Examples</a>
* [Extract (Unary)](#example_Extract_unary)

#### <a name="pkg-files">Package files</a>
[context.go](./context.go) [doc.go](./doc.go) [noop.go](./noop.go)

Expand All @@ -47,6 +51,37 @@ 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:

<details>
<summary>Click to expand code.</summary>

```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")
}
```

</details>

## <a name="ToContext">func</a> [ToContext](./context.go#L59)
``` go
func ToContext(ctx context.Context, entry *logrus.Entry) context.Context
Expand Down
19 changes: 8 additions & 11 deletions logging/logrus/ctxlogrus/examples_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,19 @@ package ctxlogrus_test
import (
"github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/ctxlogrus"
"github.com/grpc-ecosystem/go-grpc-middleware/tags"
pb_testproto "github.com/grpc-ecosystem/go-grpc-middleware/testing/testproto"
"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 Example_HandlerUsageUnaryPing() {
_ = 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 := ctxlogrus.Extract(ctx)
l.Info("some ping")
l.Info("another ping")
return &pb_testproto.PingResponse{Value: ping.Value}, nil
}
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")
}
Loading

0 comments on commit eb23b08

Please sign in to comment.