Takahiro Suzuki | d7bf820 | 2020-12-17 20:21:59 +0900 | [diff] [blame] | 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. |
| 20 | // Please refer to https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md |
| 21 | // for more information about custom-metadata. |
| 22 | package metadata // import "google.golang.org/grpc/metadata" |
| 23 | |
| 24 | import ( |
| 25 | "context" |
| 26 | "fmt" |
| 27 | "strings" |
| 28 | ) |
| 29 | |
| 30 | // DecodeKeyValue returns k, v, nil. |
| 31 | // |
| 32 | // Deprecated: use k and v directly instead. |
| 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. |
| 49 | // |
| 50 | // Keys beginning with "grpc-" are reserved for grpc-internal use only and may |
| 51 | // result in errors if set in metadata. |
| 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. |
| 70 | // |
| 71 | // Keys beginning with "grpc-" are reserved for grpc-internal use only and may |
| 72 | // result in errors if set in metadata. |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 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. |
| 147 | func 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. |
| 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}) |
| 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 | |
| 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 | |
| 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. |
| 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 |
| 209 | } |