Adding a way to inject a request ID (#1046)

* Adding a way to inject a request ID

It is very useful to associate a request ID to each incoming request,
this change allows to provide a function to do that via Server Option.
The change comes with a default function which will generate a new
request ID. The request ID is put in the request context along with a
common logger which always logs the request-id

We add gRPC interceptors to the server so it can get the request ID out
of the gRPC metadata and put it in the common logger stored in the
context so as all the log lines using the common logger from the context
will have the request ID logged

vendor/github.com/grpc-ecosystem/go-grpc-middleware/util/metautils/DOC.md

@@ -0,0 +1,114 @@
+# metautils
+`import "github.com/grpc-ecosystem/go-grpc-middleware/util/metautils"`
+
+* [Overview](#pkg-overview)
+* [Imported Packages](#pkg-imports)
+* [Index](#pkg-index)
+
+## <a name="pkg-overview">Overview</a>
+
+## <a name="pkg-imports">Imported Packages</a>
+
+- [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)
+
+## <a name="pkg-index">Index</a>
+* [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)
+
+#### <a name="pkg-files">Package files</a>
+[doc.go](./doc.go) [nicemd.go](./nicemd.go) [single_key.go](./single_key.go) 
+
+## <a name="NiceMD">type</a> [NiceMD](./nicemd.go#L14)
+``` go
+type NiceMD metadata.MD
+```
+NiceMD is a convenience wrapper definiting extra functions on the metadata.
+
+### <a name="ExtractIncoming">func</a> [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.
+
+### <a name="ExtractOutgoing">func</a> [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.
+
+### <a name="NiceMD.Add">func</a> (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.
+
+### <a name="NiceMD.Clone">func</a> (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.
+
+### <a name="NiceMD.Del">func</a> (NiceMD) [Del](./nicemd.go#L100)
+``` go
+func (m NiceMD) Del(key string) NiceMD
+```
+
+### <a name="NiceMD.Get">func</a> (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.
+
+### <a name="NiceMD.Set">func</a> (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.
+
+### <a name="NiceMD.ToIncoming">func</a> (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..
+
+### <a name="NiceMD.ToOutgoing">func</a> (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)

vendor/github.com/grpc-ecosystem/go-grpc-middleware/util/metautils/README.md

@@ -0,0 +1 @@
+DOC.md

vendor/github.com/grpc-ecosystem/go-grpc-middleware/util/metautils/doc.go

@@ -0,0 +1,19 @@
+// Copyright 2016 Michal Witkowski. All Rights Reserved.
+// See LICENSE for licensing terms.
+
+/*
+Package `metautils` provides convenience functions for dealing with gRPC metadata.MD objects inside
+Context handlers.
+
+While the upstream grpc-go package contains decent functionality (see https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md)
+they are hard to use.
+
+The majority of functions center around the NiceMD, which is a convenience wrapper around metadata.MD. For example
+the following code allows you to easily extract incoming metadata (server handler) and put it into a new client context
+metadata.
+
+  nmd := metautils.ExtractIncoming(serverCtx).Clone(":authorization", ":custom")
+  clientCtx := nmd.Set("x-client-header", "2").Set("x-another", "3").ToOutgoing(ctx)
+*/
+
+package metautils

vendor/github.com/grpc-ecosystem/go-grpc-middleware/util/metautils/nicemd.go

@@ -0,0 +1,126 @@
+// Copyright 2016 Michal Witkowski. All Rights Reserved.
+// See LICENSE for licensing terms.
+
+package metautils
+
+import (
+	"strings"
+
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+// NiceMD is a convenience wrapper definiting extra functions on the metadata.
+type NiceMD metadata.MD
+
+// 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 ExtractIncoming(ctx context.Context) NiceMD {
+	md, ok := metadata.FromIncomingContext(ctx)
+	if !ok {
+		return NiceMD(metadata.Pairs())
+	}
+	return NiceMD(md)
+}
+
+// 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 ExtractOutgoing(ctx context.Context) NiceMD {
+	md, ok := metadata.FromOutgoingContext(ctx)
+	if !ok {
+		return NiceMD(metadata.Pairs())
+	}
+	return NiceMD(md)
+}
+
+// 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 (m NiceMD) Clone(copiedKeys ...string) NiceMD {
+	newMd := NiceMD(metadata.Pairs())
+	for k, vv := range m {
+		found := false
+		if len(copiedKeys) == 0 {
+			found = true
+		} else {
+			for _, allowedKey := range copiedKeys {
+				if strings.ToLower(allowedKey) == strings.ToLower(k) {
+					found = true
+					break
+				}
+			}
+		}
+		if !found {
+			continue
+		}
+		newMd[k] = make([]string, len(vv))
+		copy(newMd[k], vv)
+	}
+	return NiceMD(newMd)
+}
+
+// ToOutgoing sets the given NiceMD as a client-side context for dispatching.
+func (m NiceMD) ToOutgoing(ctx context.Context) context.Context {
+	return metadata.NewOutgoingContext(ctx, metadata.MD(m))
+}
+
+// ToIncoming sets the given NiceMD as a server-side context for dispatching.
+//
+// This is mostly useful in ServerInterceptors..
+func (m NiceMD) ToIncoming(ctx context.Context) context.Context {
+	return metadata.NewIncomingContext(ctx, metadata.MD(m))
+}
+
+// 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 (m NiceMD) Get(key string) string {
+	k, _ := encodeKeyValue(key, "")
+	vv, ok := m[k]
+	if !ok {
+		return ""
+	}
+	return vv[0]
+}
+
+// Del retrieves a single value from the metadata.
+//
+// It works analogously to http.Header.Del, deleting all values if they exist.
+//
+// The function is binary-key safe.
+
+func (m NiceMD) Del(key string) NiceMD {
+	k, _ := encodeKeyValue(key, "")
+	delete(m, k)
+	return m
+}
+
+// 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 (m NiceMD) Set(key string, value string) NiceMD {
+	k, v := encodeKeyValue(key, value)
+	m[k] = []string{v}
+	return m
+}
+
+// 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 (m NiceMD) Add(key string, value string) NiceMD {
+	k, v := encodeKeyValue(key, value)
+	m[k] = append(m[k], v)
+	return m
+}

vendor/github.com/grpc-ecosystem/go-grpc-middleware/util/metautils/nicemd_test.go

@@ -0,0 +1,86 @@
+// Copyright 2016 Michal Witkowski. All Rights Reserved.
+// See LICENSE for licensing terms.
+
+package metautils_test
+
+import (
+	"testing"
+
+	"github.com/grpc-ecosystem/go-grpc-middleware/util/metautils"
+	"github.com/stretchr/testify/assert"
+	"golang.org/x/net/context"
+	"google.golang.org/grpc/metadata"
+)
+
+var (
+	testPairs = []string{"singlekey", "uno", "multikey", "one", "multikey", "two", "multikey", "three"}
+	parentCtx = context.WithValue(context.TODO(), "parentKey", "parentValue")
+)
+
+func assertRetainsParentContext(t *testing.T, ctx context.Context) {
+	x := ctx.Value("parentKey")
+	assert.EqualValues(t, "parentValue", x, "context must contain parentCtx")
+}
+
+func TestNiceMD_Get(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	assert.Equal(t, "uno", nmd.Get("singlekey"), "for present single-key value it should return it")
+	assert.Equal(t, "one", nmd.Get("multikey"), "for present multi-key should return first value")
+	assert.Empty(t, nmd.Get("nokey"), "for non existing key should return stuff")
+}
+
+func TestNiceMD_Del(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	assert.Equal(t, "uno", nmd.Get("singlekey"), "for present single-key value it should return it")
+	nmd.Del("singlekey").Del("doesnt exist")
+	assert.Empty(t, nmd.Get("singlekey"), "after deletion singlekey shouldn't exist")
+}
+
+func TestNiceMD_Add(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	nmd.Add("multikey", "four").Add("newkey", "something")
+	assert.EqualValues(t, []string{"one", "two", "three", "four"}, nmd["multikey"], "append should add a new four at the end")
+	assert.EqualValues(t, []string{"something"}, nmd["newkey"], "append should be able to create new keys")
+}
+
+func TestNiceMD_Set(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	nmd.Set("multikey", "one").Set("newkey", "something").Set("newkey", "another")
+	assert.EqualValues(t, []string{"one"}, nmd["multikey"], "set should override existing multi keys")
+	assert.EqualValues(t, []string{"another"}, nmd["newkey"], "set should override new keys")
+}
+
+func TestNiceMD_Clone(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	fullCopied := nmd.Clone()
+	assert.Equal(t, len(fullCopied), len(nmd), "clone full should copy all keys")
+	assert.Equal(t, "uno", fullCopied.Get("singlekey"), "full copied should have content")
+	subCopied := nmd.Clone("multikey")
+	assert.Len(t, subCopied, 1, "sub copied clone should only have one key")
+	assert.Empty(t, subCopied.Get("singlekey"), "there shouldn't be a singlekey in the subcopied")
+
+	// Test side effects and full copying:
+	assert.EqualValues(t, subCopied["multikey"], nmd["multikey"], "before overwrites multikey should have the same values")
+	subCopied["multikey"][1] = "modifiedtwo"
+	assert.NotEqual(t, subCopied["multikey"], nmd["multikey"], "before overwrites multikey should have the same values")
+}
+
+func TestNiceMD_ToOutgoing(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	nCtx := nmd.ToOutgoing(parentCtx)
+	assertRetainsParentContext(t, nCtx)
+
+	eCtx := metautils.ExtractOutgoing(nCtx).Clone().Set("newvalue", "something").ToOutgoing(nCtx)
+	assertRetainsParentContext(t, eCtx)
+	assert.NotEqual(t, metautils.ExtractOutgoing(nCtx), metautils.ExtractOutgoing(eCtx), "the niceMD pointed to by ectx and nctx are different.")
+}
+
+func TestNiceMD_ToIncoming(t *testing.T) {
+	nmd := metautils.NiceMD(metadata.Pairs(testPairs...))
+	nCtx := nmd.ToIncoming(parentCtx)
+	assertRetainsParentContext(t, nCtx)
+
+	eCtx := metautils.ExtractIncoming(nCtx).Clone().Set("newvalue", "something").ToIncoming(nCtx)
+	assertRetainsParentContext(t, eCtx)
+	assert.NotEqual(t, metautils.ExtractIncoming(nCtx), metautils.ExtractIncoming(eCtx), "the niceMD pointed to by ectx and nctx are different.")
+}

vendor/github.com/grpc-ecosystem/go-grpc-middleware/util/metautils/single_key.go

@@ -0,0 +1,22 @@
+// Copyright 2016 Michal Witkowski. All Rights Reserved.
+// See LICENSE for licensing terms.
+
+package metautils
+
+import (
+	"encoding/base64"
+	"strings"
+)
+
+const (
+	binHdrSuffix = "-bin"
+)
+
+func encodeKeyValue(k, v string) (string, string) {
+	k = strings.ToLower(k)
+	if strings.HasSuffix(k, binHdrSuffix) {
+		val := base64.StdEncoding.EncodeToString([]byte(v))
+		v = string(val)
+	}
+	return k, v
+}