]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
1 | /* |
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. | |
107c1cdb ND |
20 | // Please refer to https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md |
21 | // for more information about custom-metadata. | |
15c0b25d AP |
22 | package metadata // import "google.golang.org/grpc/metadata" |
23 | ||
24 | import ( | |
107c1cdb | 25 | "context" |
15c0b25d AP |
26 | "fmt" |
27 | "strings" | |
15c0b25d AP |
28 | ) |
29 | ||
107c1cdb ND |
30 | // DecodeKeyValue returns k, v, nil. |
31 | // | |
32 | // Deprecated: use k and v directly instead. | |
15c0b25d AP |
33 | func 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. | |
39 | type 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. | |
107c1cdb ND |
49 | // |
50 | // Keys beginning with "grpc-" are reserved for grpc-internal use only and may | |
51 | // result in errors if set in metadata. | |
15c0b25d AP |
52 | func 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. | |
107c1cdb ND |
70 | // |
71 | // Keys beginning with "grpc-" are reserved for grpc-internal use only and may | |
72 | // result in errors if set in metadata. | |
15c0b25d AP |
73 | func 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. | |
90 | func (md MD) Len() int { | |
91 | return len(md) | |
92 | } | |
93 | ||
94 | // Copy returns a copy of md. | |
95 | func (md MD) Copy() MD { | |
96 | return Join(md) | |
97 | } | |
98 | ||
107c1cdb ND |
99 | // Get obtains the values for a given key. |
100 | func (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. | |
106 | func (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. | |
115 | func (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 | ||
15c0b25d AP |
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. | |
126 | func 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 | ||
136 | type mdIncomingKey struct{} | |
137 | type mdOutgoingKey struct{} | |
138 | ||
15c0b25d AP |
139 | // NewIncomingContext creates a new context with incoming md attached. |
140 | func NewIncomingContext(ctx context.Context, md MD) context.Context { | |
141 | return context.WithValue(ctx, mdIncomingKey{}, md) | |
142 | } | |
143 | ||
107c1cdb ND |
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. | |
15c0b25d | 147 | func NewOutgoingContext(ctx context.Context, md MD) context.Context { |
107c1cdb | 148 | return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md}) |
15c0b25d AP |
149 | } |
150 | ||
107c1cdb ND |
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. | |
154 | func 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}) | |
15c0b25d AP |
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. | |
169 | func FromIncomingContext(ctx context.Context) (md MD, ok bool) { | |
170 | md, ok = ctx.Value(mdIncomingKey{}).(MD) | |
171 | return | |
172 | } | |
173 | ||
107c1cdb ND |
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. | |
180 | func 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 | ||
15c0b25d AP |
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. | |
107c1cdb ND |
191 | // Modification should be made to copies of the returned MD. |
192 | func 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 | ||
206 | type rawMD struct { | |
207 | md MD | |
208 | added [][]string | |
15c0b25d | 209 | } |