blob: cf6d1b94781ca3dba84f6c329337a91f83254e82 [file] [log] [blame]
Scott Baker2d897982019-09-24 11:50:08 -07001/*
2 *
3 * Copyright 2014 gRPC authors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18
19// Package metadata define the structure of the metadata supported by gRPC library.
20// Please refer to https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
21// for more information about custom-metadata.
22package metadata // import "google.golang.org/grpc/metadata"
23
24import (
25 "context"
26 "fmt"
27 "strings"
28)
29
30// DecodeKeyValue returns k, v, nil.
31//
32// Deprecated: use k and v directly instead.
33func DecodeKeyValue(k, v string) (string, string, error) {
34 return k, v, nil
35}
36
37// MD is a mapping from metadata keys to values. Users should use the following
38// two convenience functions New and Pairs to generate MD.
39type MD map[string][]string
40
41// New creates an MD from a given key-value map.
42//
43// Only the following ASCII characters are allowed in keys:
44// - digits: 0-9
45// - uppercase letters: A-Z (normalized to lower)
46// - lowercase letters: a-z
47// - special characters: -_.
48// Uppercase letters are automatically converted to lowercase.
49//
50// Keys beginning with "grpc-" are reserved for grpc-internal use only and may
51// result in errors if set in metadata.
52func New(m map[string]string) MD {
53 md := MD{}
54 for k, val := range m {
55 key := strings.ToLower(k)
56 md[key] = append(md[key], val)
57 }
58 return md
59}
60
61// Pairs returns an MD formed by the mapping of key, value ...
62// Pairs panics if len(kv) is odd.
63//
64// Only the following ASCII characters are allowed in keys:
65// - digits: 0-9
66// - uppercase letters: A-Z (normalized to lower)
67// - lowercase letters: a-z
68// - special characters: -_.
69// Uppercase letters are automatically converted to lowercase.
70//
71// Keys beginning with "grpc-" are reserved for grpc-internal use only and may
72// result in errors if set in metadata.
73func Pairs(kv ...string) MD {
74 if len(kv)%2 == 1 {
75 panic(fmt.Sprintf("metadata: Pairs got the odd number of input pairs for metadata: %d", len(kv)))
76 }
77 md := MD{}
78 var key string
79 for i, s := range kv {
80 if i%2 == 0 {
81 key = strings.ToLower(s)
82 continue
83 }
84 md[key] = append(md[key], s)
85 }
86 return md
87}
88
89// Len returns the number of items in md.
90func (md MD) Len() int {
91 return len(md)
92}
93
94// Copy returns a copy of md.
95func (md MD) Copy() MD {
96 return Join(md)
97}
98
99// Get obtains the values for a given key.
100func (md MD) Get(k string) []string {
101 k = strings.ToLower(k)
102 return md[k]
103}
104
105// Set sets the value of a given key with a slice of values.
106func (md MD) Set(k string, vals ...string) {
107 if len(vals) == 0 {
108 return
109 }
110 k = strings.ToLower(k)
111 md[k] = vals
112}
113
114// Append adds the values to key k, not overwriting what was already stored at that key.
115func (md MD) Append(k string, vals ...string) {
116 if len(vals) == 0 {
117 return
118 }
119 k = strings.ToLower(k)
120 md[k] = append(md[k], vals...)
121}
122
123// Join joins any number of mds into a single MD.
124// The order of values for each key is determined by the order in which
125// the mds containing those values are presented to Join.
126func Join(mds ...MD) MD {
127 out := MD{}
128 for _, md := range mds {
129 for k, v := range md {
130 out[k] = append(out[k], v...)
131 }
132 }
133 return out
134}
135
136type mdIncomingKey struct{}
137type mdOutgoingKey struct{}
138
139// NewIncomingContext creates a new context with incoming md attached.
140func NewIncomingContext(ctx context.Context, md MD) context.Context {
141 return context.WithValue(ctx, mdIncomingKey{}, md)
142}
143
144// NewOutgoingContext creates a new context with outgoing md attached. If used
145// in conjunction with AppendToOutgoingContext, NewOutgoingContext will
146// overwrite any previously-appended metadata.
147func NewOutgoingContext(ctx context.Context, md MD) context.Context {
148 return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md})
149}
150
151// AppendToOutgoingContext returns a new context with the provided kv merged
152// with any existing metadata in the context. Please refer to the
153// documentation of Pairs for a description of kv.
154func AppendToOutgoingContext(ctx context.Context, kv ...string) context.Context {
155 if len(kv)%2 == 1 {
156 panic(fmt.Sprintf("metadata: AppendToOutgoingContext got an odd number of input pairs for metadata: %d", len(kv)))
157 }
158 md, _ := ctx.Value(mdOutgoingKey{}).(rawMD)
159 added := make([][]string, len(md.added)+1)
160 copy(added, md.added)
161 added[len(added)-1] = make([]string, len(kv))
162 copy(added[len(added)-1], kv)
163 return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md.md, added: added})
164}
165
166// FromIncomingContext returns the incoming metadata in ctx if it exists. The
167// returned MD should not be modified. Writing to it may cause races.
168// Modification should be made to copies of the returned MD.
169func FromIncomingContext(ctx context.Context) (md MD, ok bool) {
170 md, ok = ctx.Value(mdIncomingKey{}).(MD)
171 return
172}
173
174// FromOutgoingContextRaw returns the un-merged, intermediary contents
175// of rawMD. Remember to perform strings.ToLower on the keys. The returned
176// MD should not be modified. Writing to it may cause races. Modification
177// should be made to copies of the returned MD.
178//
179// This is intended for gRPC-internal use ONLY.
180func FromOutgoingContextRaw(ctx context.Context) (MD, [][]string, bool) {
181 raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD)
182 if !ok {
183 return nil, nil, false
184 }
185
186 return raw.md, raw.added, true
187}
188
189// FromOutgoingContext returns the outgoing metadata in ctx if it exists. The
190// returned MD should not be modified. Writing to it may cause races.
191// Modification should be made to copies of the returned MD.
192func FromOutgoingContext(ctx context.Context) (MD, bool) {
193 raw, ok := ctx.Value(mdOutgoingKey{}).(rawMD)
194 if !ok {
195 return nil, false
196 }
197
198 mds := make([]MD, 0, len(raw.added)+1)
199 mds = append(mds, raw.md)
200 for _, vv := range raw.added {
201 mds = append(mds, Pairs(vv...))
202 }
203 return Join(mds...), ok
204}
205
206type rawMD struct {
207 md MD
208 added [][]string
209}