From c772189ad1aa54a3efbf383a41126a7b0fcdc804 Mon Sep 17 00:00:00 2001 From: Menghan Li Date: Tue, 11 May 2021 14:17:48 -0700 Subject: [PATCH 1/4] [md_doc] metadata: convert keys to lowercase in FromContext() --- metadata/metadata.go | 71 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 55 insertions(+), 16 deletions(-) diff --git a/metadata/metadata.go b/metadata/metadata.go index e4cbea91749..2215c1bc3e5 100644 --- a/metadata/metadata.go +++ b/metadata/metadata.go @@ -93,12 +93,16 @@ func (md MD) Copy() MD { } // Get obtains the values for a given key. +// +// All keys are converted to lowercase. func (md MD) Get(k string) []string { k = strings.ToLower(k) return md[k] } // Set sets the value of a given key with a slice of values. +// +// All keys are converted to lowercase. func (md MD) Set(k string, vals ...string) { if len(vals) == 0 { return @@ -107,7 +111,10 @@ func (md MD) Set(k string, vals ...string) { md[k] = vals } -// Append adds the values to key k, not overwriting what was already stored at that key. +// Append adds the values to key k, not overwriting what was already stored at +// that key. +// +// All keys are converted to lowercase. func (md MD) Append(k string, vals ...string) { if len(vals) == 0 { return @@ -117,8 +124,9 @@ func (md MD) Append(k string, vals ...string) { } // Join joins any number of mds into a single MD. -// The order of values for each key is determined by the order in which -// the mds containing those values are presented to Join. +// +// The order of values for each key is determined by the order in which the mds +// containing those values are presented to Join. func Join(mds ...MD) MD { out := MD{} for _, md := range mds { @@ -145,8 +153,12 @@ func NewOutgoingContext(ctx context.Context, md MD) context.Context { } // AppendToOutgoingContext returns a new context with the provided kv merged -// with any existing metadata in the context. Please refer to the -// documentation of Pairs for a description of kv. +// with any existing metadata in the context. Please refer to the documentation +// of Pairs for a description of kv. +// +// Unlike Pairs, the keys are not turned into lowercase immediately. Users of +// FromOutgoingContextRaw and FromOutgoingContext need to handle them +// accordingly. Read the corresponding doc for more details. func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context { if len(kv)%2 == 1 { panic(fmt.Sprintf("metadata: AppendToOutgoingContext got an odd number of input pairs for metadata: %d", len(kv))) @@ -159,20 +171,38 @@ func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md.md, added: added}) } -// FromIncomingContext returns the incoming metadata in ctx if it exists. The +// FromIncomingContext returns the incoming metadata in ctx if it exists. The // returned MD should not be modified. Writing to it may cause races. // Modification should be made to copies of the returned MD. -func FromIncomingContext(ctx context.Context) (md MD, ok bool) { - md, ok = ctx.Value(mdIncomingKey{}).(MD) - return +// +// All keys in the return MD are lowercase. +func FromIncomingContext(ctx context.Context) (MD, bool) { + md, ok := ctx.Value(mdIncomingKey{}).(MD) + if !ok { + return nil, false + } + out := MD{} + for k, v := range md { + // We need to manually convert all keys to lower case, because MD is a + // map, and there's no guarantee that the MD attached to the context is + // created using our helper functions. + key := strings.ToLower(k) + out[key] = v + } + return out, true } -// FromOutgoingContextRaw returns the un-merged, intermediary contents -// of rawMD. Remember to perform strings.ToLower on the keys. The returned -// MD should not be modified. Writing to it may cause races. Modification -// should be made to copies of the returned MD. +// FromOutgoingContextRaw returns the un-merged, intermediary contents of rawMD. +// The returned MD should not be modified. Writing to it may cause races. +// Modification should be made to copies of the returned MD. +// +// Remember to perform strings.ToLower on the keys, for both the returned MD (MD +// is a map, there's no guarantee it's created using our helper functions) and +// the extra kv pairs (AppendToOutgoingContext doesn't turn them into +// lowercase). // -// This is intended for gRPC-internal use ONLY. +// This is intended for gRPC-internal use ONLY. Users should use +// FromOutgoingContext instead. func FromOutgoingContextRaw(ctx context.Context) (MD, [][]string, bool) { raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD) if !ok { @@ -182,16 +212,25 @@ func FromOutgoingContextRaw(ctx context.Context) (MD, [][]string, bool) { return raw.md, raw.added, true } -// FromOutgoingContext returns the outgoing metadata in ctx if it exists. The +// FromOutgoingContext returns the outgoing metadata in ctx if it exists. The // returned MD should not be modified. Writing to it may cause races. // Modification should be made to copies of the returned MD. +// +// All keys in the return MD are lowercase. func FromOutgoingContext(ctx context.Context) (MD, bool) { raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD) if !ok { return nil, false } - out := raw.md.Copy() + out := MD{} + for k, v := range raw.md { + // We need to manually convert all keys to lower case, because MD is a + // map, and there's no guarantee that the MD attached to the context is + // created using our helper functions. + key := strings.ToLower(k) + out[key] = v + } for _, added := range raw.added { if len(added)%2 == 1 { panic(fmt.Sprintf("metadata: FromOutgoingContext got an odd number of input pairs for metadata: %d", len(added))) From 244a1858f5057347b6fcae3d04bbc32344d50a2c Mon Sep 17 00:00:00 2001 From: Menghan Li Date: Mon, 17 May 2021 14:55:20 -0700 Subject: [PATCH 2/4] [md_doc] c1 --- metadata/metadata.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/metadata/metadata.go b/metadata/metadata.go index 2215c1bc3e5..39dab797002 100644 --- a/metadata/metadata.go +++ b/metadata/metadata.go @@ -156,9 +156,9 @@ func NewOutgoingContext(ctx context.Context, md MD) context.Context { // with any existing metadata in the context. Please refer to the documentation // of Pairs for a description of kv. // -// Unlike Pairs, the keys are not turned into lowercase immediately. Users of -// FromOutgoingContextRaw and FromOutgoingContext need to handle them -// accordingly. Read the corresponding doc for more details. +// Unlike Pairs, the keys are not turned into lowercase. Users of +// FromOutgoingContext need to handle them accordingly. Read +// FromOutgoingContext's doc for more details. func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context { if len(kv)%2 == 1 { panic(fmt.Sprintf("metadata: AppendToOutgoingContext got an odd number of input pairs for metadata: %d", len(kv))) @@ -175,7 +175,7 @@ func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context // returned MD should not be modified. Writing to it may cause races. // Modification should be made to copies of the returned MD. // -// All keys in the return MD are lowercase. +// All keys in the returned MD are lowercase. func FromIncomingContext(ctx context.Context) (MD, bool) { md, ok := ctx.Value(mdIncomingKey{}).(MD) if !ok { From 4aa8f7bff98a7627622a1c40851c8b6878a9c5b4 Mon Sep 17 00:00:00 2001 From: Menghan Li Date: Tue, 25 May 2021 13:47:03 -0700 Subject: [PATCH 3/4] [md_doc] doc, can use the returned MD --- metadata/metadata.go | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/metadata/metadata.go b/metadata/metadata.go index 39dab797002..df2d4351e50 100644 --- a/metadata/metadata.go +++ b/metadata/metadata.go @@ -171,9 +171,7 @@ func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md.md, added: added}) } -// FromIncomingContext returns the incoming metadata in ctx if it exists. The -// returned MD should not be modified. Writing to it may cause races. -// Modification should be made to copies of the returned MD. +// FromIncomingContext returns the incoming metadata in ctx if it exists. // // All keys in the returned MD are lowercase. func FromIncomingContext(ctx context.Context) (MD, bool) { @@ -193,8 +191,6 @@ func FromIncomingContext(ctx context.Context) (MD, bool) { } // FromOutgoingContextRaw returns the un-merged, intermediary contents of rawMD. -// The returned MD should not be modified. Writing to it may cause races. -// Modification should be made to copies of the returned MD. // // Remember to perform strings.ToLower on the keys, for both the returned MD (MD // is a map, there's no guarantee it's created using our helper functions) and @@ -212,9 +208,7 @@ func FromOutgoingContextRaw(ctx context.Context) (MD, [][]string, bool) { return raw.md, raw.added, true } -// FromOutgoingContext returns the outgoing metadata in ctx if it exists. The -// returned MD should not be modified. Writing to it may cause races. -// Modification should be made to copies of the returned MD. +// FromOutgoingContext returns the outgoing metadata in ctx if it exists. // // All keys in the return MD are lowercase. func FromOutgoingContext(ctx context.Context) (MD, bool) { From 9b1cdb99052448af295d978780319aa34f0ca24f Mon Sep 17 00:00:00 2001 From: Menghan Li Date: Thu, 3 Jun 2021 13:58:24 -0700 Subject: [PATCH 4/4] [md_doc] c2 --- metadata/metadata.go | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/metadata/metadata.go b/metadata/metadata.go index df2d4351e50..8d9686375a1 100644 --- a/metadata/metadata.go +++ b/metadata/metadata.go @@ -94,7 +94,7 @@ func (md MD) Copy() MD { // Get obtains the values for a given key. // -// All keys are converted to lowercase. +// k is converted to lowercase before searching in md. func (md MD) Get(k string) []string { k = strings.ToLower(k) return md[k] @@ -102,7 +102,7 @@ func (md MD) Get(k string) []string { // Set sets the value of a given key with a slice of values. // -// All keys are converted to lowercase. +// k is converted to lowercase before storing in md. func (md MD) Set(k string, vals ...string) { if len(vals) == 0 { return @@ -114,7 +114,7 @@ func (md MD) Set(k string, vals ...string) { // Append adds the values to key k, not overwriting what was already stored at // that key. // -// All keys are converted to lowercase. +// k is converted to lowercase before storing in md. func (md MD) Append(k string, vals ...string) { if len(vals) == 0 { return @@ -155,10 +155,6 @@ func NewOutgoingContext(ctx context.Context, md MD) context.Context { // AppendToOutgoingContext returns a new context with the provided kv merged // with any existing metadata in the context. Please refer to the documentation // of Pairs for a description of kv. -// -// Unlike Pairs, the keys are not turned into lowercase. Users of -// FromOutgoingContext need to handle them accordingly. Read -// FromOutgoingContext's doc for more details. func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context { if len(kv)%2 == 1 { panic(fmt.Sprintf("metadata: AppendToOutgoingContext got an odd number of input pairs for metadata: %d", len(kv))) @@ -210,7 +206,7 @@ func FromOutgoingContextRaw(ctx context.Context) (MD, [][]string, bool) { // FromOutgoingContext returns the outgoing metadata in ctx if it exists. // -// All keys in the return MD are lowercase. +// All keys in the returned MD are lowercase. func FromOutgoingContext(ctx context.Context) (MD, bool) { raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD) if !ok {