snapshot of https://github.com/grpc/grpc-go.git (master, 2026-09-15; blobs > 131072B omitted)

metadata/metadata.go

@@ -0,0 +1,426 @@
+/*
+ *
+ * Copyright 2014 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Package metadata define the structure of the metadata supported by gRPC library.
+// Please refer to https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
+// for more information about custom-metadata.
+package metadata // import "google.golang.org/grpc/metadata"
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+
+	"google.golang.org/grpc/internal"
+)
+
+func init() {
+	internal.FromOutgoingContextRaw = fromOutgoingContextRaw
+}
+
+// DecodeKeyValue returns k, v, nil.
+//
+// Deprecated: use k and v directly instead.
+func DecodeKeyValue(k, v string) (string, string, error) {
+	return k, v, nil
+}
+
+// MD is a mapping from metadata keys to values. Users should use the following
+// two convenience functions New and Pairs to generate MD.
+type MD map[string][]string
+
+// New creates an MD from a given key-value map.
+//
+// Only the following ASCII characters are allowed in keys:
+//   - digits: 0-9
+//   - uppercase letters: A-Z (normalized to lower)
+//   - lowercase letters: a-z
+//   - special characters: -_.
+//
+// Uppercase letters are automatically converted to lowercase.
+//
+// Keys beginning with "grpc-" are reserved for grpc-internal use only and may
+// result in errors if set in metadata.
+func New(m map[string]string) MD {
+	md := make(MD, len(m))
+	for k, val := range m {
+		key := strings.ToLower(k)
+		md[key] = append(md[key], val)
+	}
+	return md
+}
+
+// Pairs returns an MD formed by the mapping of key, value ...
+// Pairs panics if len(kv) is odd.
+//
+// Only the following ASCII characters are allowed in keys:
+//   - digits: 0-9
+//   - uppercase letters: A-Z (normalized to lower)
+//   - lowercase letters: a-z
+//   - special characters: -_.
+//
+// Uppercase letters are automatically converted to lowercase.
+//
+// Keys beginning with "grpc-" are reserved for grpc-internal use only and may
+// result in errors if set in metadata.
+func Pairs(kv ...string) MD {
+	if len(kv)%2 == 1 {
+		panic(fmt.Sprintf("metadata: Pairs got the odd number of input pairs for metadata: %d", len(kv)))
+	}
+	md := make(MD, len(kv)/2)
+	for i := 0; i < len(kv); i += 2 {
+		key := strings.ToLower(kv[i])
+		md[key] = append(md[key], kv[i+1])
+	}
+	return md
+}
+
+// loggableMetadataKeys is the set of metadata keys whose values are known not
+// to carry credentials or other sensitive data, and are therefore safe to print
+// verbatim in String. Values for any key not in this set are redacted. Keys are
+// in metadata's canonical lowercase form.
+//
+// The list is intentionally restricted to standardized gRPC and HTTP/2 protocol
+// headers. Everything else, including all application-defined keys, is
+// censored.
+// Note that this list might change as we add/remove support for
+// metadata types.
+var loggableMetadataKeys = map[string]bool{
+	"content-type":               true,
+	"te":                         true,
+	"user-agent":                 true,
+	"grpc-encoding":              true,
+	"grpc-accept-encoding":       true,
+	"grpc-timeout":               true,
+	"grpc-status":                true,
+	"grpc-message-type":          true,
+	"grpc-previous-rpc-attempts": true,
+	"grpc-retry-pushback-ms":     true,
+}
+
+// String implements fmt.Stringer to allow metadata to be printed when stored in
+// a context.
+//
+// To avoid accidentally leaking credentials or other sensitive data (for
+// example via log(md), or by logging a value that happens to contain metadata),
+// String reports only keys on an allowlist of standardized, non-sensitive
+// protocol headers (see loggableMetadataKeys). Every other key is omitted
+// entirely, along with its values, because a key name may itself be sensitive;
+// only the number of omitted keys is reported, as "<N redacted>". This is a
+// best-effort guard against accidents, not a security boundary: a caller that
+// genuinely wants the full contents can still print map[string][]string(md)
+// directly.
+//
+// Note that this only affects verbs that use the Stringer, such as %v and %s.
+// The %#v verb prints the underlying map with all values and is not redacted.
+// Users should not rely on the output of this method to be stable
+// # Experimental
+//
+// Notice: This API is EXPERIMENTAL and may be changed or removed in a later
+// release.
+func (md MD) String() string {
+	keys := make([]string, 0, len(md))
+	for k := range md {
+		if loggableMetadataKeys[strings.ToLower(k)] {
+			keys = append(keys, k)
+		}
+	}
+	sort.Strings(keys)
+
+	var sb strings.Builder
+	sb.WriteString("map[")
+	for i, k := range keys {
+		if i > 0 {
+			sb.WriteByte(' ')
+		}
+		fmt.Fprintf(&sb, "%s:%v", k, md[k])
+	}
+	if redacted := len(md) - len(keys); redacted > 0 {
+		if len(keys) > 0 {
+			sb.WriteByte(' ')
+		}
+		fmt.Fprintf(&sb, "<%d redacted>", redacted)
+	}
+	sb.WriteByte(']')
+	return sb.String()
+}
+
+// Len returns the number of items in md.
+func (md MD) Len() int {
+	return len(md)
+}
+
+// Copy returns a copy of md.
+func (md MD) Copy() MD {
+	out := make(MD, len(md))
+	for k, v := range md {
+		out[k] = copyOf(v)
+	}
+	return out
+}
+
+// Get obtains the values for a given key.
+//
+// k is converted to lowercase before searching in md.
+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.
+//
+// k is converted to lowercase before storing in md.
+func (md MD) Set(k string, vals ...string) {
+	if len(vals) == 0 {
+		return
+	}
+	k = strings.ToLower(k)
+	md[k] = vals
+}
+
+// Append adds the values to key k, not overwriting what was already stored at
+// that key.
+//
+// k is converted to lowercase before storing in md.
+func (md MD) Append(k string, vals ...string) {
+	if len(vals) == 0 {
+		return
+	}
+	k = strings.ToLower(k)
+	md[k] = append(md[k], vals...)
+}
+
+// Delete removes the values for a given key k which is converted to lowercase
+// before removing it from md.
+func (md MD) Delete(k string) {
+	k = strings.ToLower(k)
+	delete(md, k)
+}
+
+// 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.
+func Join(mds ...MD) MD {
+	out := MD{}
+	for _, md := range mds {
+		for k, v := range md {
+			out[k] = append(out[k], v...)
+		}
+	}
+	return out
+}
+
+type mdIncomingKey struct{}
+type mdOutgoingKey struct{}
+
+// NewIncomingContext creates a new context with incoming md attached. md must
+// not be modified after calling this function.
+func NewIncomingContext(ctx context.Context, md MD) context.Context {
+	return context.WithValue(ctx, mdIncomingKey{}, md)
+}
+
+// NewOutgoingContext creates a new context with outgoing md attached. If used
+// in conjunction with AppendToOutgoingContext, NewOutgoingContext will
+// overwrite any previously-appended metadata. md must not be modified after
+// calling this function.
+func NewOutgoingContext(ctx context.Context, md MD) context.Context {
+	return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md})
+}
+
+// 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.
+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)))
+	}
+	md, _ := ctx.Value(mdOutgoingKey{}).(rawMD)
+	added := make([][]string, len(md.added)+1)
+	copy(added, md.added)
+	kvCopy := make([]string, 0, len(kv))
+	for i := 0; i < len(kv); i += 2 {
+		kvCopy = append(kvCopy, strings.ToLower(kv[i]), kv[i+1])
+	}
+	added[len(added)-1] = kvCopy
+	return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md.md, added: added})
+}
+
+// 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) {
+	md, ok := ctx.Value(mdIncomingKey{}).(MD)
+	if !ok {
+		return nil, false
+	}
+	out := make(MD, len(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] = copyOf(v)
+	}
+	return out, true
+}
+
+// ValueFromIncomingContext returns the metadata value corresponding to the metadata
+// key from the incoming metadata if it exists. Keys are matched in a case insensitive
+// manner.
+func ValueFromIncomingContext(ctx context.Context, key string) []string {
+	md, ok := ctx.Value(mdIncomingKey{}).(MD)
+	if !ok {
+		return nil
+	}
+
+	if v, ok := md[key]; ok {
+		return copyOf(v)
+	}
+	for k, v := range md {
+		// Case insensitive comparison: MD is a map, and there's no guarantee
+		// that the MD attached to the context is created using our helper
+		// functions.
+		if strings.EqualFold(k, key) {
+			return copyOf(v)
+		}
+	}
+	return nil
+}
+
+func copyOf(v []string) []string {
+	vals := make([]string, len(v))
+	copy(vals, v)
+	return vals
+}
+
+// fromOutgoingContextRaw returns the un-merged, intermediary contents of rawMD.
+//
+// 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).
+func fromOutgoingContextRaw(ctx context.Context) (MD, [][]string, bool) {
+	raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD)
+	if !ok {
+		return nil, nil, false
+	}
+
+	return raw.md, raw.added, true
+}
+
+// FromOutgoingContext returns the outgoing metadata in ctx if it exists.
+//
+// All keys in the returned MD are lowercase.
+func FromOutgoingContext(ctx context.Context) (MD, bool) {
+	raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD)
+	if !ok {
+		return nil, false
+	}
+
+	mdSize := len(raw.md)
+	for i := range raw.added {
+		mdSize += len(raw.added[i]) / 2
+	}
+
+	out := make(MD, mdSize)
+	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] = copyOf(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)))
+		}
+
+		for i := 0; i < len(added); i += 2 {
+			key := strings.ToLower(added[i])
+			out[key] = append(out[key], added[i+1])
+		}
+	}
+	return out, ok
+}
+
+// ValueFromOutgoingContext returns the metadata value corresponding to the
+// metadata key from the outgoing metadata if it exists. Keys are matched in a
+// case-insensitive manner.
+//
+// Unlike FromOutgoingContext, this does not copy the entire outgoing metadata.
+func ValueFromOutgoingContext(ctx context.Context, key string) []string {
+	raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD)
+	if !ok {
+		return nil
+	}
+
+	key = strings.ToLower(key)
+	// Unlike ValueFromIncomingContext, this can't return as soon as raw.md is
+	// checked: raw.added still needs to be walked and accumulated regardless.
+	// The else below prevents that from overwriting an exact match with an
+	// unrelated case-insensitive one.
+	var matchedMD []string
+	if v, ok := raw.md[key]; ok {
+		matchedMD = v
+	} else {
+		for k, v := range raw.md {
+			// Case insensitive comparison: MD is a map, and there's no
+			// guarantee that the MD attached to the context is created using
+			// our helper functions.
+			if strings.EqualFold(k, key) {
+				matchedMD = v
+				break
+			}
+		}
+	}
+
+	// Defer allocating vals until raw.added actually has a match, so a match
+	// found only in raw.md doesn't pay for both a copyOf and a growing
+	// append.
+	var vals []string
+	for _, added := range raw.added {
+		if len(added)%2 == 1 {
+			panic(fmt.Sprintf("metadata: ValueFromOutgoingContext got an odd number of input pairs for metadata: %d", len(added)))
+		}
+
+		// Case insensitive, like FromOutgoingContext: added isn't guaranteed
+		// lowercase, though AppendToOutgoingContext already lowercases it in
+		// practice, so try the cheap exact match first.
+		for i := 0; i < len(added); i += 2 {
+			if added[i] == key || strings.EqualFold(added[i], key) {
+				if vals == nil {
+					vals = make([]string, 0, len(matchedMD)+1)
+					vals = append(vals, matchedMD...)
+				}
+				vals = append(vals, added[i+1])
+			}
+		}
+	}
+
+	if vals == nil && matchedMD != nil {
+		return copyOf(matchedMD)
+	}
+	return vals
+}
+
+type rawMD struct {
+	md    MD
+	added [][]string
+}

metadata/metadata_test.go

@@ -0,0 +1,677 @@
+/*
+ *
+ * Copyright 2014 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package metadata
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"google.golang.org/grpc/internal/grpctest"
+)
+
+const defaultTestTimeout = 10 * time.Second
+
+type s struct {
+	grpctest.Tester
+}
+
+func Test(t *testing.T) {
+	grpctest.RunSubTests(t, s{})
+}
+
+func (s) TestPairsMD(t *testing.T) {
+	for _, test := range []struct {
+		// input
+		kv []string
+		// output
+		md MD
+	}{
+		{[]string{}, MD{}},
+		{[]string{"k1", "v1", "k1", "v2"}, MD{"k1": []string{"v1", "v2"}}},
+	} {
+		md := Pairs(test.kv...)
+		if !reflect.DeepEqual(md, test.md) {
+			t.Fatalf("Pairs(%v) = %v, want %v", test.kv, md, test.md)
+		}
+	}
+}
+
+func (s) TestCopy(t *testing.T) {
+	const key, val = "key", "val"
+	orig := Pairs(key, val)
+	cpy := orig.Copy()
+	if !reflect.DeepEqual(orig, cpy) {
+		t.Errorf("copied value not equal to the original, got %v, want %v", cpy, orig)
+	}
+	orig[key][0] = "foo"
+	if v := cpy[key][0]; v != val {
+		t.Errorf("change in original should not affect copy, got %q, want %q", v, val)
+	}
+}
+
+func (s) TestJoin(t *testing.T) {
+	for _, test := range []struct {
+		mds  []MD
+		want MD
+	}{
+		{[]MD{}, MD{}},
+		{[]MD{Pairs("foo", "bar")}, Pairs("foo", "bar")},
+		{[]MD{Pairs("foo", "bar"), Pairs("foo", "baz")}, Pairs("foo", "bar", "foo", "baz")},
+		{[]MD{Pairs("foo", "bar"), Pairs("foo", "baz"), Pairs("zip", "zap")}, Pairs("foo", "bar", "foo", "baz", "zip", "zap")},
+	} {
+		md := Join(test.mds...)
+		if !reflect.DeepEqual(md, test.want) {
+			t.Errorf("context's metadata is %v, want %v", md, test.want)
+		}
+	}
+}
+
+func (s) TestGet(t *testing.T) {
+	for _, test := range []struct {
+		md       MD
+		key      string
+		wantVals []string
+	}{
+		{md: Pairs("My-Optional-Header", "42"), key: "My-Optional-Header", wantVals: []string{"42"}},
+		{md: Pairs("Header", "42", "Header", "43", "Header", "44", "other", "1"), key: "HEADER", wantVals: []string{"42", "43", "44"}},
+		{md: Pairs("HEADER", "10"), key: "HEADER", wantVals: []string{"10"}},
+	} {
+		vals := test.md.Get(test.key)
+		if !reflect.DeepEqual(vals, test.wantVals) {
+			t.Errorf("value of metadata %v is %v, want %v", test.key, vals, test.wantVals)
+		}
+	}
+}
+
+func (s) TestSet(t *testing.T) {
+	for _, test := range []struct {
+		md      MD
+		setKey  string
+		setVals []string
+		want    MD
+	}{
+		{
+			md:      Pairs("My-Optional-Header", "42", "other-key", "999"),
+			setKey:  "Other-Key",
+			setVals: []string{"1"},
+			want:    Pairs("my-optional-header", "42", "other-key", "1"),
+		},
+		{
+			md:      Pairs("My-Optional-Header", "42"),
+			setKey:  "Other-Key",
+			setVals: []string{"1", "2", "3"},
+			want:    Pairs("my-optional-header", "42", "other-key", "1", "other-key", "2", "other-key", "3"),
+		},
+		{
+			md:      Pairs("My-Optional-Header", "42"),
+			setKey:  "Other-Key",
+			setVals: []string{},
+			want:    Pairs("my-optional-header", "42"),
+		},
+	} {
+		test.md.Set(test.setKey, test.setVals...)
+		if !reflect.DeepEqual(test.md, test.want) {
+			t.Errorf("value of metadata is %v, want %v", test.md, test.want)
+		}
+	}
+}
+
+func (s) TestAppend(t *testing.T) {
+	for _, test := range []struct {
+		md         MD
+		appendKey  string
+		appendVals []string
+		want       MD
+	}{
+		{
+			md:         Pairs("My-Optional-Header", "42"),
+			appendKey:  "Other-Key",
+			appendVals: []string{"1"},
+			want:       Pairs("my-optional-header", "42", "other-key", "1"),
+		},
+		{
+			md:         Pairs("My-Optional-Header", "42"),
+			appendKey:  "my-OptIoNal-HeAder",
+			appendVals: []string{"1", "2", "3"},
+			want: Pairs("my-optional-header", "42", "my-optional-header", "1",
+				"my-optional-header", "2", "my-optional-header", "3"),
+		},
+		{
+			md:         Pairs("My-Optional-Header", "42"),
+			appendKey:  "my-OptIoNal-HeAder",
+			appendVals: []string{},
+			want:       Pairs("my-optional-header", "42"),
+		},
+	} {
+		test.md.Append(test.appendKey, test.appendVals...)
+		if !reflect.DeepEqual(test.md, test.want) {
+			t.Errorf("value of metadata is %v, want %v", test.md, test.want)
+		}
+	}
+}
+
+func (s) TestDelete(t *testing.T) {
+	for _, test := range []struct {
+		md        MD
+		deleteKey string
+		want      MD
+	}{
+		{
+			md:        Pairs("My-Optional-Header", "42"),
+			deleteKey: "My-Optional-Header",
+			want:      Pairs(),
+		},
+		{
+			md:        Pairs("My-Optional-Header", "42"),
+			deleteKey: "Other-Key",
+			want:      Pairs("my-optional-header", "42"),
+		},
+		{
+			md:        Pairs("My-Optional-Header", "42"),
+			deleteKey: "my-OptIoNal-HeAder",
+			want:      Pairs(),
+		},
+	} {
+		test.md.Delete(test.deleteKey)
+		if !reflect.DeepEqual(test.md, test.want) {
+			t.Errorf("value of metadata is %v, want %v", test.md, test.want)
+		}
+	}
+}
+
+func (s) TestFromIncomingContext(t *testing.T) {
+	md := Pairs(
+		"X-My-Header-1", "42",
+	)
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	// Verify that we lowercase if callers directly modify md
+	md["X-INCORRECT-UPPERCASE"] = []string{"foo"}
+	ctx = NewIncomingContext(ctx, md)
+
+	result, found := FromIncomingContext(ctx)
+	if !found {
+		t.Fatal("FromIncomingContext must return metadata")
+	}
+	expected := MD{
+		"x-my-header-1":         []string{"42"},
+		"x-incorrect-uppercase": []string{"foo"},
+	}
+	if !reflect.DeepEqual(result, expected) {
+		t.Errorf("FromIncomingContext returned %#v, expected %#v", result, expected)
+	}
+
+	// ensure modifying result does not modify the value in the context
+	result["new_key"] = []string{"foo"}
+	result["x-my-header-1"][0] = "mutated"
+
+	result2, found := FromIncomingContext(ctx)
+	if !found {
+		t.Fatal("FromIncomingContext must return metadata")
+	}
+	if !reflect.DeepEqual(result2, expected) {
+		t.Errorf("FromIncomingContext after modifications returned %#v, expected %#v", result2, expected)
+	}
+}
+
+func (s) TestValueFromIncomingContext(t *testing.T) {
+	md := Pairs(
+		"X-My-Header-1", "42",
+		"X-My-Header-2", "43-1",
+		"X-My-Header-2", "43-2",
+		"x-my-header-3", "44",
+	)
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	// Verify that we lowercase if callers directly modify md
+	md["X-INCORRECT-UPPERCASE"] = []string{"foo"}
+	ctx = NewIncomingContext(ctx, md)
+
+	for _, test := range []struct {
+		key  string
+		want []string
+	}{
+		{
+			key:  "x-my-header-1",
+			want: []string{"42"},
+		},
+		{
+			key:  "x-my-header-2",
+			want: []string{"43-1", "43-2"},
+		},
+		{
+			key:  "x-my-header-3",
+			want: []string{"44"},
+		},
+		{
+			key:  "x-unknown",
+			want: nil,
+		},
+		{
+			key:  "x-incorrect-uppercase",
+			want: []string{"foo"},
+		},
+	} {
+		v := ValueFromIncomingContext(ctx, test.key)
+		if !reflect.DeepEqual(v, test.want) {
+			t.Errorf("value of metadata is %v, want %v", v, test.want)
+		}
+	}
+}
+
+func (s) TestAppendToOutgoingContext(t *testing.T) {
+	// Pre-existing metadata
+	tCtx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	ctx := NewOutgoingContext(tCtx, Pairs("k1", "v1", "k2", "v2"))
+	ctx = AppendToOutgoingContext(ctx, "k1", "v3")
+	ctx = AppendToOutgoingContext(ctx, "k1", "v4")
+	md, ok := FromOutgoingContext(ctx)
+	if !ok {
+		t.Errorf("Expected MD to exist in ctx, but got none")
+	}
+	want := Pairs("k1", "v1", "k1", "v3", "k1", "v4", "k2", "v2")
+	if !reflect.DeepEqual(md, want) {
+		t.Errorf("context's metadata is %v, want %v", md, want)
+	}
+
+	// No existing metadata
+	ctx = AppendToOutgoingContext(tCtx, "k1", "v1")
+	md, ok = FromOutgoingContext(ctx)
+	if !ok {
+		t.Errorf("Expected MD to exist in ctx, but got none")
+	}
+	want = Pairs("k1", "v1")
+	if !reflect.DeepEqual(md, want) {
+		t.Errorf("context's metadata is %v, want %v", md, want)
+	}
+}
+
+func (s) TestAppendToOutgoingContext_Repeated(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+
+	for i := 0; i < 100; i = i + 2 {
+		ctx1 := AppendToOutgoingContext(ctx, "k", strconv.Itoa(i))
+		ctx2 := AppendToOutgoingContext(ctx, "k", strconv.Itoa(i+1))
+
+		md1, _ := FromOutgoingContext(ctx1)
+		md2, _ := FromOutgoingContext(ctx2)
+
+		if reflect.DeepEqual(md1, md2) {
+			t.Fatalf("md1, md2 = %v, %v; should not be equal", md1, md2)
+		}
+
+		ctx = ctx1
+	}
+}
+
+func (s) TestAppendToOutgoingContext_FromKVSlice(t *testing.T) {
+	const k, v = "a", "b"
+	kv := []string{k, v}
+	tCtx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	ctx := AppendToOutgoingContext(tCtx, kv...)
+	md, _ := FromOutgoingContext(ctx)
+	if md[k][0] != v {
+		t.Fatalf("md[%q] = %q; want %q", k, md[k], v)
+	}
+	kv[1] = "xxx"
+	md, _ = FromOutgoingContext(ctx)
+	if md[k][0] != v {
+		t.Fatalf("md[%q] = %q; want %q", k, md[k], v)
+	}
+}
+
+func (s) TestValueFromOutgoingContext(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+
+	md := Pairs(
+		"X-My-Header-1", "42",
+		"x-my-header-3", "44",
+		"k1", "v1",
+		"k2", "v2",
+	)
+	// Verify that we match case-insensitively even if callers directly
+	// modify md.
+	md["X-INCORRECT-UPPERCASE"] = []string{"foo"}
+	ctx = NewOutgoingContext(ctx, md)
+	ctx = AppendToOutgoingContext(ctx, "x-my-header-2", "43-1")
+	ctx = AppendToOutgoingContext(ctx, "X-My-Header-2", "43-2")
+	ctx = AppendToOutgoingContext(ctx, "k1", "v3")
+	ctx = AppendToOutgoingContext(ctx, "k1", "v4")
+
+	for _, test := range []struct {
+		key  string
+		want []string
+	}{
+		{
+			key:  "x-my-header-1",
+			want: []string{"42"},
+		},
+		{
+			// Split across two AppendToOutgoingContext calls (raw.added) —
+			// must accumulate across both, in call order.
+			key:  "x-my-header-2",
+			want: []string{"43-1", "43-2"},
+		},
+		{
+			key:  "x-my-header-3",
+			want: []string{"44"},
+		},
+		{
+			key:  "x-unknown",
+			want: nil,
+		},
+		{
+			key:  "x-incorrect-uppercase",
+			want: []string{"foo"},
+		},
+		{
+			// Present in both raw.md and two later AppendToOutgoingContext
+			// calls — must accumulate across all three, in order.
+			key:  "k1",
+			want: []string{"v1", "v3", "v4"},
+		},
+	} {
+		v := ValueFromOutgoingContext(ctx, test.key)
+		if diff := cmp.Diff(test.want, v); diff != "" {
+			t.Errorf("ValueFromOutgoingContext(ctx, %q) returned unexpected diff (-want +got):\n%s", test.key, diff)
+		}
+	}
+}
+
+func (s) TestValueFromOutgoingContext_NoMetadata(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+
+	if v := ValueFromOutgoingContext(ctx, "x-my-header-1"); v != nil {
+		t.Errorf("ValueFromOutgoingContext on context with no outgoing metadata = %v, want nil", v)
+	}
+}
+
+func (s) TestValueFromOutgoingContext_AddedCaseInsensitive(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	ctx = context.WithValue(ctx, mdOutgoingKey{}, rawMD{added: [][]string{{"X-My-Header", "42"}}})
+
+	v := ValueFromOutgoingContext(ctx, "x-my-header")
+	if diff := cmp.Diff([]string{"42"}, v); diff != "" {
+		t.Errorf("ValueFromOutgoingContext(ctx, \"x-my-header\") returned unexpected diff (-want +got):\n%s", diff)
+	}
+}
+
+func (s) TestValueFromOutgoingContext_PanicsOnOddPairs(t *testing.T) {
+	defer func() {
+		if r := recover(); r == nil {
+			t.Fatal("ValueFromOutgoingContext did not panic on an odd number of pairs in added")
+		}
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	ctx = context.WithValue(ctx, mdOutgoingKey{}, rawMD{added: [][]string{{"key-without-a-value"}}})
+
+	ValueFromOutgoingContext(ctx, "key-without-a-value")
+}
+
+// Old/slow approach to adding metadata to context
+func Benchmark_AddingMetadata_ContextManipulationApproach(b *testing.B) {
+	// TODO: Add in N=1-100 tests once Go1.6 support is removed.
+	const num = 10
+	for n := 0; n < b.N; n++ {
+		ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+		defer cancel()
+		for i := 0; i < num; i++ {
+			md, _ := FromOutgoingContext(ctx)
+			NewOutgoingContext(ctx, Join(Pairs("k1", "v1", "k2", "v2"), md))
+		}
+	}
+}
+
+// Newer/faster approach to adding metadata to context
+func BenchmarkAppendToOutgoingContext(b *testing.B) {
+	const num = 10
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	for n := 0; n < b.N; n++ {
+		for i := 0; i < num; i++ {
+			ctx = AppendToOutgoingContext(ctx, "k1", "v1", "k2", "v2")
+		}
+	}
+}
+
+func BenchmarkFromOutgoingContext(b *testing.B) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	ctx = NewOutgoingContext(ctx, MD{"k3": {"v3", "v4"}})
+	ctx = AppendToOutgoingContext(ctx, "k1", "v1", "k2", "v2")
+
+	for n := 0; n < b.N; n++ {
+		FromOutgoingContext(ctx)
+	}
+}
+
+// Reading one key out of many staged headers
+func BenchmarkValueFromOutgoingContextVsFromOutgoingContext(b *testing.B) {
+	for _, numHeaders := range []int{1, 10, 50} {
+		ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+		defer cancel()
+		md := MD{}
+		for i := 0; i < numHeaders; i++ {
+			md[strconv.Itoa(i)] = []string{strconv.Itoa(i)}
+		}
+		ctx = NewOutgoingContext(ctx, md)
+		ctx = AppendToOutgoingContext(ctx, "target-key", "target-value")
+
+		b.Run(fmt.Sprintf("FromOutgoingContext/n=%d", numHeaders), func(b *testing.B) {
+			for b.Loop() {
+				FromOutgoingContext(ctx)
+			}
+		})
+
+		b.Run(fmt.Sprintf("ValueFromOutgoingContext/n=%d", numHeaders), func(b *testing.B) {
+			for b.Loop() {
+				ValueFromOutgoingContext(ctx, "target-key")
+			}
+		})
+	}
+}
+
+func BenchmarkFromIncomingContext(b *testing.B) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	md := Pairs("X-My-Header-1", "42")
+	ctx = NewIncomingContext(ctx, md)
+
+	b.ResetTimer()
+	for n := 0; n < b.N; n++ {
+		FromIncomingContext(ctx)
+	}
+}
+
+func BenchmarkValueFromIncomingContext(b *testing.B) {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	md := Pairs("X-My-Header-1", "42")
+	ctx = NewIncomingContext(ctx, md)
+
+	b.Run("key-found", func(b *testing.B) {
+		for n := 0; n < b.N; n++ {
+			result := ValueFromIncomingContext(ctx, "x-my-header-1")
+			if len(result) != 1 {
+				b.Fatal("ensures not optimized away")
+			}
+		}
+	})
+
+	b.Run("key-not-found", func(b *testing.B) {
+		for n := 0; n < b.N; n++ {
+			result := ValueFromIncomingContext(ctx, "key-not-found")
+			if len(result) != 0 {
+				b.Fatal("ensures not optimized away")
+			}
+		}
+	})
+}
+
+func BenchmarkValueFromOutgoingContext(b *testing.B) {
+	// Realistic-length gRPC metadata keys, not "k1"/"k2"/"k3": short keys
+	// understate the cost of strings.EqualFold relative to a cheap exact
+	// match, which matters for the key-found cases below.
+	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+	defer cancel()
+	ctx = NewOutgoingContext(ctx, MD{"content-type": {"application/grpc"}})
+	ctx = AppendToOutgoingContext(ctx, "grpc-timeout", "10S", "x-request-id", "abc-def-123")
+
+	b.Run("key-found", func(b *testing.B) {
+		for b.Loop() {
+			ValueFromOutgoingContext(ctx, "grpc-timeout")
+		}
+	})
+
+	b.Run("key-not-found", func(b *testing.B) {
+		for b.Loop() {
+			ValueFromOutgoingContext(ctx, "x-does-not-exist")
+		}
+	})
+
+	// Key present in both raw.md ("content-type") and raw.added (appended
+	// below) — exercises the accumulate-across-both path, not just
+	// append-to-nil.
+	bothCtx := AppendToOutgoingContext(ctx, "content-type", "application/grpc+proto")
+	b.Run("key-found-in-md-and-added", func(b *testing.B) {
+		for b.Loop() {
+			ValueFromOutgoingContext(bothCtx, "content-type")
+		}
+	})
+}
+
+// TestString verifies that String shows keys and values only for keys known to
+// be safe to log, omits every other key (including its name) and reports only
+// the count of omitted keys, and never panics on nil/empty inputs.
+func (s) TestString(t *testing.T) {
+	tests := []struct {
+		name string
+		md   MD
+		want string
+	}{
+		{
+			name: "empty",
+			md:   MD{},
+			want: "map[]",
+		},
+		{
+			name: "nil",
+			md:   nil,
+			want: "map[]",
+		},
+		{
+			name: "safe-key-shown",
+			md:   Pairs("content-type", "application/grpc"),
+			want: "map[content-type:[application/grpc]]",
+		},
+		{
+			// A safe key with multiple values shows all of them.
+			name: "safe-key-multi-value",
+			md:   Pairs("grpc-accept-encoding", "gzip", "grpc-accept-encoding", "snappy"),
+			want: "map[grpc-accept-encoding:[gzip snappy]]",
+		},
+		{
+			// nil/empty value slices must not panic; a safe key shows [].
+			name: "safe-key-nil-value",
+			md:   MD{"content-type": nil},
+			want: "map[content-type:[]]",
+		},
+		{
+			// A redacted key with a nil value slice still redacts, no panic.
+			name: "redacted-key-nil-value",
+			md:   MD{"authorization": nil},
+			want: "map[<1 redacted>]",
+		},
+		{
+			// Bracket characters in a safe value are passed through verbatim.
+			name: "safe-value-with-brackets",
+			md:   MD{"content-type": []string{"a]b ["}},
+			want: "map[content-type:[a]b []]",
+		},
+		{
+			// Keys differing only in case are sorted byte-wise (uppercase
+			// first); both still match the case-insensitive safelist.
+			name: "case-only-collision",
+			md:   MD{"Content-Type": []string{"a"}, "content-type": []string{"b"}},
+			want: "map[Content-Type:[a] content-type:[b]]",
+		},
+		{
+			// A sensitive key is omitted entirely, including its name; only the
+			// count is reported.
+			name: "sensitive-key-redacted",
+			md:   Pairs("authorization", "Bearer super-secret-token"),
+			want: "map[<1 redacted>]",
+		},
+		{
+			// Application-defined keys are omitted; the key name (which may
+			// itself be sensitive) is never shown.
+			name: "custom-key-redacted",
+			md:   Pairs("x-my-app-secret", "hunter2"),
+			want: "map[<1 redacted>]",
+		},
+		{
+			// A single key with multiple values counts as one redacted key, and
+			// the value count is not leaked.
+			name: "multi-value-redacted",
+			md:   Pairs("cookie", "a=1", "cookie", "b=2"),
+			want: "map[<1 redacted>]",
+		},
+		{
+			// Multiple redacted keys are reported by count only.
+			name: "multiple-redacted-keys",
+			md:   Pairs("authorization", "tok", "cookie", "x"),
+			want: "map[<2 redacted>]",
+		},
+		{
+			// Safe keys are shown (sorted) and non-safe keys are summarized by a
+			// trailing count.
+			name: "mixed-safe-and-redacted",
+			md:   Pairs("grpc-encoding", "gzip", "authorization", "tok", "user-agent", "grpc-go/x"),
+			want: "map[grpc-encoding:[gzip] user-agent:[grpc-go/x] <1 redacted>]",
+		},
+		{
+			// Keys built via map literal are not canonicalized to lowercase;
+			// the safelist match is case-insensitive so a safe key is still
+			// shown.
+			name: "uppercase-safe-key-shown",
+			md:   MD{"Content-Type": []string{"application/grpc"}},
+			want: "map[Content-Type:[application/grpc]]",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := test.md.String(); got != test.want {
+				t.Errorf("MD.String() = %q, want %q", got, test.want)
+			}
+		})
+	}
+}