vendor/google.golang.org/grpc/metadata/metadata.go

   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://grpc.io/docs/guides/wire.html for more information about custom-metadata.
  21 package metadata // import "google.golang.org/grpc/metadata"
  22
  23 import (
  24         "fmt"
  25         "strings"
  26
  27         "golang.org/x/net/context"
  28 )
  29
  30 // DecodeKeyValue returns k, v, nil.  It is deprecated and should not be used.
  31 func DecodeKeyValue(k, v string) (string, string, error) {
  32         return k, v, nil
  33 }
  34
  35 // MD is a mapping from metadata keys to values. Users should use the following
  36 // two convenience functions New and Pairs to generate MD.
  37 type MD map[string][]string
  38
  39 // New creates an MD from a given key-value map.
  40 //
  41 // Only the following ASCII characters are allowed in keys:
  42 //  - digits: 0-9
  43 //  - uppercase letters: A-Z (normalized to lower)
  44 //  - lowercase letters: a-z
  45 //  - special characters: -_.
  46 // Uppercase letters are automatically converted to lowercase.
  47 //
  48 // Keys beginning with "grpc-" are reserved for grpc-internal use only and may
  49 // result in errors if set in metadata.
  50 func New(m map[string]string) MD {
  51         md := MD{}
  52         for k, val := range m {
  53                 key := strings.ToLower(k)
  54                 md[key] = append(md[key], val)
  55         }
  56         return md
  57 }
  58
  59 // Pairs returns an MD formed by the mapping of key, value ...
  60 // Pairs panics if len(kv) is odd.
  61 //
  62 // Only the following ASCII characters are allowed in keys:
  63 //  - digits: 0-9
  64 //  - uppercase letters: A-Z (normalized to lower)
  65 //  - lowercase letters: a-z
  66 //  - special characters: -_.
  67 // Uppercase letters are automatically converted to lowercase.
  68 //
  69 // Keys beginning with "grpc-" are reserved for grpc-internal use only and may
  70 // result in errors if set in metadata.
  71 func Pairs(kv ...string) MD {
  72         if len(kv)%2 == 1 {
  73                 panic(fmt.Sprintf("metadata: Pairs got the odd number of input pairs for metadata: %d", len(kv)))
  74         }
  75         md := MD{}
  76         var key string
  77         for i, s := range kv {
  78                 if i%2 == 0 {
  79                         key = strings.ToLower(s)
  80                         continue
  81                 }
  82                 md[key] = append(md[key], s)
  83         }
  84         return md
  85 }
  86
  87 // Len returns the number of items in md.
  88 func (md MD) Len() int {
  89         return len(md)
  90 }
  91
  92 // Copy returns a copy of md.
  93 func (md MD) Copy() MD {
  94         return Join(md)
  95 }
  96
  97 // Join joins any number of mds into a single MD.
  98 // The order of values for each key is determined by the order in which
  99 // the mds containing those values are presented to Join.
 100 func Join(mds ...MD) MD {
 101         out := MD{}
 102         for _, md := range mds {
 103                 for k, v := range md {
 104                         out[k] = append(out[k], v...)
 105                 }
 106         }
 107         return out
 108 }
 109
 110 type mdIncomingKey struct{}
 111 type mdOutgoingKey struct{}
 112
 113 // NewIncomingContext creates a new context with incoming md attached.
 114 func NewIncomingContext(ctx context.Context, md MD) context.Context {
 115         return context.WithValue(ctx, mdIncomingKey{}, md)
 116 }
 117
 118 // NewOutgoingContext creates a new context with outgoing md attached.
 119 func NewOutgoingContext(ctx context.Context, md MD) context.Context {
 120         return context.WithValue(ctx, mdOutgoingKey{}, md)
 121 }
 122
 123 // FromIncomingContext returns the incoming metadata in ctx if it exists.  The
 124 // returned MD should not be modified. Writing to it may cause races.
 125 // Modification should be made to copies of the returned MD.
 126 func FromIncomingContext(ctx context.Context) (md MD, ok bool) {
 127         md, ok = ctx.Value(mdIncomingKey{}).(MD)
 128         return
 129 }
 130
 131 // FromOutgoingContext returns the outgoing metadata in ctx if it exists.  The
 132 // returned MD should not be modified. Writing to it may cause races.
 133 // Modification should be made to the copies of the returned MD.
 134 func FromOutgoingContext(ctx context.Context) (md MD, ok bool) {
 135         md, ok = ctx.Value(mdOutgoingKey{}).(MD)
 136         return
 137 }