update vendor

Signed-off-by: Jess Frazelle <acidburn@microsoft.com>

vendor/google.golang.org/grpc/Documentation/compression.md

@@ -0,0 +1,80 @@
+# Compression
+
+The preferred method for configuring message compression on both clients and
+servers is to use
+[`encoding.RegisterCompressor`](https://godoc.org/google.golang.org/grpc/encoding#RegisterCompressor)
+to register an implementation of a compression algorithm.  See
+`grpc/encoding/gzip/gzip.go` for an example of how to implement one.
+
+Once a compressor has been registered on the client-side, RPCs may be sent using
+it via the
+[`UseCompressor`](https://godoc.org/google.golang.org/grpc#UseCompressor)
+`CallOption`.  Remember that `CallOption`s may be turned into defaults for all
+calls from a `ClientConn` by using the
+[`WithDefaultCallOptions`](https://godoc.org/google.golang.org/grpc#WithDefaultCallOptions)
+`DialOption`.  If `UseCompressor` is used and the corresponding compressor has
+not been installed, an `Internal` error will be returned to the application
+before the RPC is sent.
+
+Server-side, registered compressors will be used automatically to decode request
+messages and encode the responses.  Servers currently always respond using the
+same compression method specified by the client.  If the corresponding
+compressor has not been registered, an `Unimplemented` status will be returned
+to the client.
+
+## Deprecated API
+
+There is a deprecated API for setting compression as well.  It is not
+recommended for use.  However, if you were previously using it, the following
+section may be helpful in understanding how it works in combination with the new
+API.
+
+### Client-Side
+
+There are two legacy functions and one new function to configure compression:
+
+```go
+func WithCompressor(grpc.Compressor) DialOption {}
+func WithDecompressor(grpc.Decompressor) DialOption {}
+func UseCompressor(name) CallOption {}
+```
+
+For outgoing requests, the following rules are applied in order:
+1. If `UseCompressor` is used, messages will be compressed using the compressor
+   named.
+   * If the compressor named is not registered, an Internal error is returned
+     back to the client before sending the RPC.
+   * If UseCompressor("identity"), no compressor will be used, but "identity"
+     will be sent in the header to the server.
+1. If `WithCompressor` is used, messages will be compressed using that
+   compressor implementation.
+1. Otherwise, outbound messages will be uncompressed.
+
+For incoming responses, the following rules are applied in order:
+1. If `WithDecompressor` is used and it matches the message's encoding, it will
+   be used.
+1. If a registered compressor matches the response's encoding, it will be used.
+1. Otherwise, the stream will be closed and an `Unimplemented` status error will
+   be returned to the application.
+
+### Server-Side
+
+There are two legacy functions to configure compression:
+```go
+func RPCCompressor(grpc.Compressor) ServerOption {}
+func RPCDecompressor(grpc.Decompressor) ServerOption {}
+```
+
+For incoming requests, the following rules are applied in order:
+1. If `RPCDecompressor` is used and that decompressor matches the request's
+   encoding: it will be used.
+1. If a registered compressor matches the request's encoding, it will be used.
+1. Otherwise, an `Unimplemented` status will be returned to the client.
+
+For outgoing responses, the following rules are applied in order:
+1. If `RPCCompressor` is used, that compressor will be used to compress all
+   response messages.
+1. If compression was used for the incoming request and a registered compressor
+   supports it, that same compression method will be used for the outgoing
+   response.
+1. Otherwise, no compression will be used for the outgoing response.

vendor/google.golang.org/grpc/Documentation/concurrency.md

@@ -0,0 +1,33 @@
+# Concurrency
+
+In general, gRPC-go provides a concurrency-friendly API. What follows are some
+guidelines.
+
+## Clients
+
+A [ClientConn][client-conn] can safely be accessed concurrently. Using
+[helloworld][helloworld] as an example, one could share the `ClientConn` across
+multiple goroutines to create multiple `GreeterClient` types. In this case, RPCs
+would be sent in parallel.
+
+## Streams
+
+When using streams, one must take care to avoid calling either `SendMsg` or
+`RecvMsg` multiple times against the same [Stream][stream] from different
+goroutines. In other words, it's safe to have a goroutine calling `SendMsg` and
+another goroutine calling `RecvMsg` on the same stream at the same time. But it
+is not safe to call `SendMsg` on the same stream in different goroutines, or to
+call `RecvMsg` on the same stream in different goroutines.
+
+## Servers
+
+Each RPC handler attached to a registered server will be invoked in its own
+goroutine. For example, [SayHello][say-hello] will be invoked in its own
+goroutine. The same is true for service handlers for streaming RPCs, as seen
+in the route guide example [here][route-guide-stream].
+
+[helloworld]: https://github.com/grpc/grpc-go/blob/master/examples/helloworld/greeter_client/main.go#L43
+[client-conn]: https://godoc.org/google.golang.org/grpc#ClientConn
+[stream]: https://godoc.org/google.golang.org/grpc#Stream
+[say-hello]: https://github.com/grpc/grpc-go/blob/master/examples/helloworld/greeter_server/main.go#L41
+[route-guide-stream]: https://github.com/grpc/grpc-go/blob/master/examples/route_guide/server/server.go#L126

vendor/google.golang.org/grpc/Documentation/encoding.md

@@ -0,0 +1,146 @@
+# Encoding
+
+The gRPC API for sending and receiving is based upon *messages*.  However,
+messages cannot be transmitted directly over a network; they must first be
+converted into *bytes*.  This document describes how gRPC-Go converts messages
+into bytes and vice-versa for the purposes of network transmission.
+
+## Codecs (Serialization and Deserialization)
+
+A `Codec` contains code to serialize a message into a byte slice (`Marshal`) and
+deserialize a byte slice back into a message (`Unmarshal`).  `Codec`s are
+registered by name into a global registry maintained in the `encoding` package.
+
+### Implementing a `Codec`
+
+A typical `Codec` will be implemented in its own package with an `init` function
+that registers itself, and is imported anonymously.  For example:
+
+```go
+package proto
+
+import "google.golang.org/grpc/encoding"
+
+func init() {
+	encoding.RegisterCodec(protoCodec{})
+}
+
+// ... implementation of protoCodec ...
+```
+
+For an example, gRPC's implementation of the `proto` codec can be found in
+[`encoding/proto`](https://godoc.org/google.golang.org/grpc/encoding/proto).
+
+### Using a `Codec`
+
+By default, gRPC registers and uses the "proto" codec, so it is not necessary to
+do this in your own code to send and receive proto messages.  To use another
+`Codec` from a client or server:
+
+```go
+package myclient
+
+import _ "path/to/another/codec"
+```
+
+`Codec`s, by definition, must be symmetric, so the same desired `Codec` should
+be registered in both client and server binaries.
+
+On the client-side, to specify a `Codec` to use for message transmission, the
+`CallOption` `CallContentSubtype` should be used as follows:
+
+```go
+	response, err := myclient.MyCall(ctx, request, grpc.CallContentSubtype("mycodec"))
+```
+
+As a reminder, all `CallOption`s may be converted into `DialOption`s that become
+the default for all RPCs sent through a client using `grpc.WithDefaultCallOptions`:
+
+```go
+	myclient := grpc.Dial(ctx, target, grpc.WithDefaultCallOptions(grpc.CallContentSubtype("mycodec")))
+```
+
+When specified in either of these ways, messages will be encoded using this
+codec and sent along with headers indicating the codec (`content-type` set to
+`application/grpc+<codec name>`).
+
+On the server-side, using a `Codec` is as simple as registering it into the
+global registry (i.e. `import`ing it).  If a message is encoded with the content
+sub-type supported by a registered `Codec`, it will be used automatically for
+decoding the request and encoding the response.  Otherwise, for
+backward-compatibility reasons, gRPC will attempt to use the "proto" codec.  In
+an upcoming change (tracked in [this
+issue](https://github.com/grpc/grpc-go/issues/1824)), such requests will be
+rejected with status code `Unimplemented` instead.
+
+## Compressors (Compression and Decompression)
+
+Sometimes, the resulting serialization of a message is not space-efficient, and
+it may be beneficial to compress this byte stream before transmitting it over
+the network.  To facilitate this operation, gRPC supports a mechanism for
+performing compression and decompression.
+
+A `Compressor` contains code to compress and decompress by wrapping `io.Writer`s
+and `io.Reader`s, respectively.  (The form of `Compress` and `Decompress` were
+chosen to most closely match Go's standard package
+[implementations](https://golang.org/pkg/compress/) of compressors.  Like
+`Codec`s, `Compressor`s are registered by name into a global registry maintained
+in the `encoding` package.
+
+### Implementing a `Compressor`
+
+A typical `Compressor` will be implemented in its own package with an `init`
+function that registers itself, and is imported anonymously.  For example:
+
+```go
+package gzip
+
+import "google.golang.org/grpc/encoding"
+
+func init() {
+	encoding.RegisterCompressor(compressor{})
+}
+
+// ... implementation of compressor ...
+```
+
+An implementation of a `gzip` compressor can be found in
+[`encoding/gzip`](https://godoc.org/google.golang.org/grpc/encoding/gzip).
+
+### Using a `Compressor`
+
+By default, gRPC does not register or use any compressors.  To use a
+`Compressor` from a client or server:
+
+```go
+package myclient
+
+import _ "google.golang.org/grpc/encoding/gzip"
+```
+
+`Compressor`s, by definition, must be symmetric, so the same desired
+`Compressor` should be registered in both client and server binaries.
+
+On the client-side, to specify a `Compressor` to use for message transmission,
+the `CallOption` `UseCompressor` should be used as follows:
+
+```go
+	response, err := myclient.MyCall(ctx, request, grpc.UseCompressor("gzip"))
+```
+
+As a reminder, all `CallOption`s may be converted into `DialOption`s that become
+the default for all RPCs sent through a client using `grpc.WithDefaultCallOptions`:
+
+```go
+	myclient := grpc.Dial(ctx, target, grpc.WithDefaultCallOptions(grpc.UseCompresor("gzip")))
+```
+
+When specified in either of these ways, messages will be compressed using this
+compressor and sent along with headers indicating the compressor
+(`content-coding` set to `<compressor name>`).
+
+On the server-side, using a `Compressor` is as simple as registering it into the
+global registry (i.e. `import`ing it).  If a message is compressed with the
+content coding supported by a registered `Compressor`, it will be used
+automatically for decompressing the request and compressing the response.
+Otherwise, the request will be rejected with status code `Unimplemented`.

vendor/google.golang.org/grpc/Documentation/gomock-example.md

@@ -0,0 +1,182 @@
+# Mocking Service for gRPC
+
+[Example code unary RPC](https://github.com/grpc/grpc-go/tree/master/examples/helloworld/mock_helloworld)
+
+[Example code streaming RPC](https://github.com/grpc/grpc-go/tree/master/examples/route_guide/mock_routeguide)
+
+## Why?
+
+To test client-side logic without the overhead of connecting to a real server. Mocking enables users to write light-weight unit tests to check functionalities on client-side without invoking RPC calls to a server.
+
+## Idea: Mock the client stub that connects to the server.
+
+We use Gomock to mock the client interface (in the generated code) and programmatically set its methods to expect and return pre-determined values. This enables users to write tests around the client logic and use this mocked stub while making RPC calls.
+
+## How to use Gomock?
+
+Documentation on Gomock can be found [here](https://github.com/golang/mock).
+A quick reading of the documentation should enable users to follow the code below.
+
+Consider a gRPC service based on following proto file:
+
+```proto
+//helloworld.proto
+
+package helloworld;
+
+message HelloRequest {
+    string name = 1;
+}
+
+message HelloReply {
+    string name = 1;
+}
+
+service Greeter {
+    rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+```
+
+The generated file helloworld.pb.go will have a client interface for each service defined in the proto file. This interface will have methods corresponding to each rpc inside that service.
+
+```Go
+type GreeterClient interface {
+    SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error)
+}
+```
+
+The generated code also contains a struct that implements this interface.
+
+```Go
+type greeterClient struct {
+   cc *grpc.ClientConn
+}
+func (c *greeterClient) SayHello(ctx context.Context, in *HelloRequest, opts ...grpc.CallOption) (*HelloReply, error){
+    // ...
+    // gRPC specific code here
+    // ...
+}
+```
+
+Along with this the generated code has a method to create an instance of this struct.
+```Go
+func NewGreeterClient(cc *grpc.ClientConn) GreeterClient
+```
+
+The user code uses this function to create an instance of the struct greeterClient which then can be used to make rpc calls to the server.
+We will mock this interface GreeterClient and use an instance of that mock to make rpc calls. These calls instead of going to server will return pre-determined values.
+
+To create a mock we’ll use [mockgen](https://github.com/golang/mock#running-mockgen).
+From the directory ``` examples/helloworld/ ``` run ``` mockgen google.golang.org/grpc/examples/helloworld/helloworld GreeterClient > mock_helloworld/hw_mock.go ```
+
+Notice that in the above command we specify GreeterClient as the interface to be mocked.
+
+The user test code can import the package generated by mockgen along with library package gomock to write unit tests around client-side logic.
+```Go
+import "github.com/golang/mock/gomock"
+import hwmock "google.golang.org/grpc/examples/helloworld/mock_helloworld"
+```
+
+An instance of the mocked interface can be created as:
+```Go
+mockGreeterClient := hwmock.NewMockGreeterClient(ctrl)
+```
+This mocked object can be programmed to expect calls to its methods and return pre-determined values. For instance, we can program mockGreeterClient to expect a call to its method SayHello and return a HelloReply with message “Mocked RPC”.
+
+```Go
+mockGreeterClient.EXPECT().SayHello(
+    gomock.Any(), // expect any value for first parameter
+    gomock.Any(), // expect any value for second parameter
+).Return(&helloworld.HelloReply{Message: “Mocked RPC”}, nil)
+```
+
+gomock.Any() indicates that the parameter can have any value or type. We can indicate specific values for built-in types with gomock.Eq().
+However, if the test code needs to specify the parameter to have a proto message type, we can replace gomock.Any() with an instance of a struct that implements gomock.Matcher interface.
+
+```Go
+type rpcMsg struct {
+    msg proto.Message
+}
+
+func (r *rpcMsg) Matches(msg interface{}) bool {
+    m, ok := msg.(proto.Message)
+    if !ok {
+        return false
+    }
+    return proto.Equal(m, r.msg)
+}
+
+func (r *rpcMsg) String() string {
+    return fmt.Sprintf("is %s", r.msg)
+}
+
+...
+
+req := &helloworld.HelloRequest{Name: "unit_test"}
+mockGreeterClient.EXPECT().SayHello(
+    gomock.Any(),
+    &rpcMsg{msg: req},
+).Return(&helloworld.HelloReply{Message: "Mocked Interface"}, nil)
+```
+
+## Mock streaming RPCs:
+
+For our example we consider the case of bi-directional streaming RPCs. Concretely, we'll write a test for RouteChat function from the route guide example to demonstrate how to write mocks for streams.
+
+RouteChat is a bi-directional streaming RPC, which means calling RouteChat returns a stream that can __Send__ and __Recv__ messages to  and from the server, respectively. We'll start by creating a mock of this stream interface returned by RouteChat and then we'll mock the client interface and set expectation on the method RouteChat to return our mocked stream.
+
+### Generating mocking code:
+Like before we'll use [mockgen](https://github.com/golang/mock#running-mockgen). From the `examples/route_guide` directory run:  `mockgen google.golang.org/grpc/examples/route_guide/routeguide RouteGuideClient,RouteGuide_RouteChatClient > mock_route_guide/rg_mock.go`
+
+Notice that we are mocking both client(`RouteGuideClient`) and stream(`RouteGuide_RouteChatClient`) interfaces here.
+
+This will create a file `rg_mock.go` under directory `mock_route_guide`. This file contins all the mocking code we need to write our test.
+
+In our test code, like before, we import the this mocking code along with the generated code
+
+```go
+import (
+    rgmock "google.golang.org/grpc/examples/route_guide/mock_routeguide"
+    rgpb "google.golang.org/grpc/examples/route_guide/routeguide"
+)
+```
+
+Now conside a test that takes the RouteGuide client object as a parameter, makes a RouteChat rpc call and sends a message on the resulting stream. Furthermore, this test expects to see the same message to be received on the stream. 
+
+```go
+var msg = ...
+
+// Creates a RouteChat call and sends msg on it.
+// Checks if the received message was equal to msg.
+func testRouteChat(client rgb.RouteChatClient) error{
+    ...
+}
+```
+
+We can inject our mock in here by simply passing it as an argument to the method.
+
+Creating mock for stream interface:
+
+```go
+    stream := rgmock.NewMockRouteGuide_RouteChatClient(ctrl)
+}
+```
+
+Setting Expectations:
+
+```go
+    stream.EXPECT().Send(gomock.Any()).Return(nil)
+    stream.EXPECT().Recv().Return(msg, nil)
+```
+
+Creating mock for client interface:
+
+```go
+    rgclient := rgmock.NewMockRouteGuideClient(ctrl)
+```
+
+Setting Expectations:
+
+```go
+    rgclient.EXPECT().RouteChat(gomock.Any()).Return(stream, nil)
+```

vendor/google.golang.org/grpc/Documentation/grpc-auth-support.md

@@ -0,0 +1,78 @@
+# Authentication
+
+As outlined in the [gRPC authentication guide](https://grpc.io/docs/guides/auth.html) there are a number of different mechanisms for asserting identity between an client and server. We'll present some code-samples here demonstrating how to provide TLS support encryption and identity assertions as well as passing OAuth2 tokens to services that support it.
+
+# Enabling TLS on a gRPC client
+
+```Go
+conn, err := grpc.Dial(serverAddr, grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")))
+```
+
+# Enabling TLS on a gRPC server
+
+```Go
+creds, err := credentials.NewServerTLSFromFile(certFile, keyFile)
+if err != nil {
+  log.Fatalf("Failed to generate credentials %v", err)
+}
+lis, err := net.Listen("tcp", ":0")
+server := grpc.NewServer(grpc.Creds(creds))
+...
+server.Serve(lis)
+```
+
+# OAuth2
+
+For an example of how to configure client and server to use OAuth2 tokens, see
+[here](https://github.com/grpc/grpc-go/blob/master/examples/oauth/).
+
+## Validating a token on the server
+
+Clients may use
+[metadata.MD](https://godoc.org/google.golang.org/grpc/metadata#MD)
+to store tokens and other authentication-related data. To gain access to the
+`metadata.MD` object, a server may use
+[metadata.FromIncomingContext](https://godoc.org/google.golang.org/grpc/metadata#FromIncomingContext).
+With a reference to `metadata.MD` on the server, one needs to simply lookup the
+`authorization` key. Note, all keys stored within `metadata.MD` are normalized
+to lowercase. See [here](https://godoc.org/google.golang.org/grpc/metadata#New).
+
+It is possible to configure token validation for all RPCs using an interceptor.
+A server may configure either a
+[grpc.UnaryInterceptor](https://godoc.org/google.golang.org/grpc#UnaryInterceptor)
+or a
+[grpc.StreamInterceptor](https://godoc.org/google.golang.org/grpc#StreamInterceptor).
+
+## Adding a token to all outgoing client RPCs
+
+To send an OAuth2 token with each RPC, a client may configure the
+`grpc.DialOption`
+[grpc.WithPerRPCCredentials](https://godoc.org/google.golang.org/grpc#WithPerRPCCredentials).
+Alternatively, a client may also use the `grpc.CallOption`
+[grpc.PerRPCCredentials](https://godoc.org/google.golang.org/grpc#PerRPCCredentials)
+on each invocation of an RPC.
+
+To create a `credentials.PerRPCCredentials`, use
+[oauth.NewOauthAccess](https://godoc.org/google.golang.org/grpc/credentials/oauth#NewOauthAccess).
+Note, the OAuth2 implementation of `grpc.PerRPCCredentials` requires a client to use
+[grpc.WithTransportCredentials](https://godoc.org/google.golang.org/grpc#WithTransportCredentials)
+to prevent any insecure transmission of tokens.
+
+# Authenticating with Google
+
+## Google Compute Engine (GCE)
+
+```Go
+conn, err := grpc.Dial(serverAddr, grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")), grpc.WithPerRPCCredentials(oauth.NewComputeEngine()))
+```
+
+## JWT
+
+```Go
+jwtCreds, err := oauth.NewServiceAccountFromFile(*serviceAccountKeyFile, *oauthScope)
+if err != nil {
+  log.Fatalf("Failed to create JWT credentials: %v", err)
+}
+conn, err := grpc.Dial(serverAddr, grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")), grpc.WithPerRPCCredentials(jwtCreds))
+```
+

vendor/google.golang.org/grpc/Documentation/grpc-metadata.md

@@ -0,0 +1,227 @@
+# Metadata
+
+gRPC supports sending metadata between client and server.
+This doc shows how to send and receive metadata in gRPC-go.
+
+## Background
+
+Four kinds of service method:
+
+- [Unary RPC](https://grpc.io/docs/guides/concepts.html#unary-rpc)
+- [Server streaming RPC](https://grpc.io/docs/guides/concepts.html#server-streaming-rpc)
+- [Client streaming RPC](https://grpc.io/docs/guides/concepts.html#client-streaming-rpc)
+- [Bidirectional streaming RPC](https://grpc.io/docs/guides/concepts.html#bidirectional-streaming-rpc)
+
+And concept of [metadata](https://grpc.io/docs/guides/concepts.html#metadata).
+
+## Constructing metadata
+
+A metadata can be created using package [metadata](https://godoc.org/google.golang.org/grpc/metadata).
+The type MD is actually a map from string to a list of strings:
+
+```go
+type MD map[string][]string
+```
+
+Metadata can be read like a normal map.
+Note that the value type of this map is `[]string`,
+so that users can attach multiple values using a single key.
+
+### Creating a new metadata
+
+A metadata can be created from a `map[string]string` using function `New`:
+
+```go
+md := metadata.New(map[string]string{"key1": "val1", "key2": "val2"})
+```
+
+Another way is to use `Pairs`.
+Values with the same key will be merged into a list:
+
+```go
+md := metadata.Pairs(
+    "key1", "val1",
+    "key1", "val1-2", // "key1" will have map value []string{"val1", "val1-2"}
+    "key2", "val2",
+)
+```
+
+__Note:__ all the keys will be automatically converted to lowercase,
+so "key1" and "kEy1" will be the same key and their values will be merged into the same list.
+This happens for both `New` and `Pairs`.
+
+### Storing binary data in metadata
+
+In metadata, keys are always strings. But values can be strings or binary data.
+To store binary data value in metadata, simply add "-bin" suffix to the key.
+The values with "-bin" suffixed keys will be encoded when creating the metadata:
+
+```go
+md := metadata.Pairs(
+    "key", "string value",
+    "key-bin", string([]byte{96, 102}), // this binary data will be encoded (base64) before sending
+                                        // and will be decoded after being transferred.
+)
+```
+
+## Retrieving metadata from context
+
+Metadata can be retrieved from context using `FromIncomingContext`:
+
+```go
+func (s *server) SomeRPC(ctx context.Context, in *pb.SomeRequest) (*pb.SomeResponse, err) {
+    md, ok := metadata.FromIncomingContext(ctx)
+    // do something with metadata
+}
+```
+
+## Sending and receiving metadata - client side
+
+[//]: # "TODO: uncomment next line after example source added"
+[//]: # "Real metadata sending and receiving examples are available [here](TODO:example_dir)."
+
+### Sending metadata
+
+There are two ways to send metadata to the server. The recommended way is to append kv pairs to the context using
+`AppendToOutgoingContext`. This can be used with or without existing metadata on the context. When there is no prior
+metadata, metadata is added; when metadata already exists on the context, kv pairs are merged in.
+
+```go
+// create a new context with some metadata
+ctx := metadata.AppendToOutgoingContext(ctx, "k1", "v1", "k1", "v2", "k2", "v3")
+
+// later, add some more metadata to the context (e.g. in an interceptor)
+ctx := metadata.AppendToOutgoingContext(ctx, "k3", "v4")
+
+// make unary RPC
+response, err := client.SomeRPC(ctx, someRequest)
+
+// or make streaming RPC
+stream, err := client.SomeStreamingRPC(ctx)
+```
+
+Alternatively, metadata may be attached to the context using `NewOutgoingContext`. However, this
+replaces any existing metadata in the context, so care must be taken to preserve the existing
+metadata if desired. This is slower than using `AppendToOutgoingContext`. An example of this
+is below:
+
+```go
+// create a new context with some metadata
+md := metadata.Pairs("k1", "v1", "k1", "v2", "k2", "v3")
+ctx := metadata.NewOutgoingContext(context.Background(), md)
+
+// later, add some more metadata to the context (e.g. in an interceptor)
+md, _ := metadata.FromOutgoingContext(ctx)
+newMD := metadata.Pairs("k3", "v3")
+ctx = metadata.NewContext(ctx, metadata.Join(metadata.New(send), newMD))
+
+// make unary RPC
+response, err := client.SomeRPC(ctx, someRequest)
+
+// or make streaming RPC
+stream, err := client.SomeStreamingRPC(ctx)
+```
+
+### Receiving metadata
+
+Metadata that a client can receive includes header and trailer.
+
+#### Unary call
+
+Header and trailer sent along with a unary call can be retrieved using function [Header](https://godoc.org/google.golang.org/grpc#Header) and [Trailer](https://godoc.org/google.golang.org/grpc#Trailer) in [CallOption](https://godoc.org/google.golang.org/grpc#CallOption):
+
+```go
+var header, trailer metadata.MD // variable to store header and trailer
+r, err := client.SomeRPC(
+    ctx,
+    someRequest,
+    grpc.Header(&header),    // will retrieve header
+    grpc.Trailer(&trailer),  // will retrieve trailer
+)
+
+// do something with header and trailer
+```
+
+#### Streaming call
+
+For streaming calls including:
+
+- Server streaming RPC
+- Client streaming RPC
+- Bidirectional streaming RPC
+
+Header and trailer can be retrieved from the returned stream using function `Header` and `Trailer` in interface [ClientStream](https://godoc.org/google.golang.org/grpc#ClientStream):
+
+```go
+stream, err := client.SomeStreamingRPC(ctx)
+
+// retrieve header
+header, err := stream.Header()
+
+// retrieve trailer
+trailer := stream.Trailer()
+
+```
+
+## Sending and receiving metadata - server side
+
+[//]: # "TODO: uncomment next line after example source added"
+[//]: # "Real metadata sending and receiving examples are available [here](TODO:example_dir)."
+
+### Receiving metadata
+
+To read metadata sent by the client, the server needs to retrieve it from RPC context.
+If it is a unary call, the RPC handler's context can be used.
+For streaming calls, the server needs to get context from the stream.
+
+#### Unary call
+
+```go
+func (s *server) SomeRPC(ctx context.Context, in *pb.someRequest) (*pb.someResponse, error) {
+    md, ok := metadata.FromIncomingContext(ctx)
+    // do something with metadata
+}
+```
+
+#### Streaming call
+
+```go
+func (s *server) SomeStreamingRPC(stream pb.Service_SomeStreamingRPCServer) error {
+    md, ok := metadata.FromIncomingContext(stream.Context()) // get context from stream
+    // do something with metadata
+}
+```
+
+### Sending metadata
+
+#### Unary call
+
+To send header and trailer to client in unary call, the server can call [SendHeader](https://godoc.org/google.golang.org/grpc#SendHeader) and [SetTrailer](https://godoc.org/google.golang.org/grpc#SetTrailer) functions in module [grpc](https://godoc.org/google.golang.org/grpc).
+These two functions take a context as the first parameter.
+It should be the RPC handler's context or one derived from it:
+
+```go
+func (s *server) SomeRPC(ctx context.Context, in *pb.someRequest) (*pb.someResponse, error) {
+    // create and send header
+    header := metadata.Pairs("header-key", "val")
+    grpc.SendHeader(ctx, header)
+    // create and set trailer
+    trailer := metadata.Pairs("trailer-key", "val")
+    grpc.SetTrailer(ctx, trailer)
+}
+```
+
+#### Streaming call
+
+For streaming calls, header and trailer can be sent using function `SendHeader` and `SetTrailer` in interface [ServerStream](https://godoc.org/google.golang.org/grpc#ServerStream):
+
+```go
+func (s *server) SomeStreamingRPC(stream pb.Service_SomeStreamingRPCServer) error {
+    // create and send header
+    header := metadata.Pairs("header-key", "val")
+    stream.SendHeader(header)
+    // create and set trailer
+    trailer := metadata.Pairs("trailer-key", "val")
+    stream.SetTrailer(trailer)
+}
+```

vendor/google.golang.org/grpc/Documentation/log_levels.md

@@ -0,0 +1,49 @@
+# Log Levels
+
+This document describes the different log levels supported by the grpc-go
+library, and under what conditions they should be used.
+
+### Info
+
+Info messages are for informational purposes and may aid in the debugging of
+applications or the gRPC library.
+
+Examples:
+- The name resolver received an update.
+- The balancer updated its picker.
+- Significant gRPC state is changing.
+
+At verbosity of 0 (the default), any single info message should not be output
+more than once every 5 minutes under normal operation.
+
+### Warning
+
+Warning messages indicate problems that are non-fatal for the application, but
+could lead to unexpected behavior or subsequent errors.
+
+Examples:
+- Resolver could not resolve target name.
+- Error received while connecting to a server.
+- Lost or corrupt connection with remote endpoint.
+
+### Error
+
+Error messages represent errors in the usage of gRPC that cannot be returned to
+the application as errors, or internal gRPC-Go errors that are recoverable.
+
+Internal errors are detected during gRPC tests and will result in test failures.
+
+Examples:
+- Invalid arguments passed to a function that cannot return an error.
+- An internal error that cannot be returned or would be inappropriate to return
+  to the user.
+
+### Fatal
+
+Fatal errors are severe internal errors that are unrecoverable.  These lead
+directly to panics, and are avoided as much as possible.
+
+Example:
+- Internal invariant was violated.
+- User attempted an action that cannot return an error gracefully, but would
+  lead to an invalid state if performed.

vendor/google.golang.org/grpc/Documentation/rpc-errors.md

@@ -0,0 +1,68 @@
+# RPC Errors
+
+All service method handlers should return `nil` or errors from the
+`status.Status` type. Clients have direct access to the errors.
+
+Upon encountering an error, a gRPC server method handler should create a
+`status.Status`. In typical usage, one would use [status.New][new-status]
+passing in an appropriate [codes.Code][code] as well as a description of the
+error to produce a `status.Status`. Calling [status.Err][status-err] converts
+the `status.Status` type into an `error`. As a convenience method, there is also
+[status.Error][status-error] which obviates the conversion step. Compare:
+
+```
+st := status.New(codes.NotFound, "some description")
+err := st.Err()
+
+// vs.
+
+err := status.Error(codes.NotFound, "some description")
+```
+
+## Adding additional details to errors
+
+In some cases, it may be necessary to add details for a particular error on the
+server side. The [status.WithDetails][with-details] method exists for this
+purpose. Clients may then read those details by first converting the plain
+`error` type back to a [status.Status][status] and then using
+[status.Details][details].
+
+## Example
+
+The [example][example] demonstrates the API discussed above and shows how to add
+information about rate limits to the error message using `status.Status`.
+
+To run the example, first start the server:
+
+```
+$ go run examples/rpc_errors/server/main.go
+```
+
+In a separate session, run the client:
+
+```
+$ go run examples/rpc_errors/client/main.go
+```
+
+On the first run of the client, all is well:
+
+```
+2018/03/12 19:39:33 Greeting: Hello world
+```
+
+Upon running the client a second time, the client exceeds the rate limit and
+receives an error with details:
+
+```
+2018/03/19 16:42:01 Quota failure: violations:<subject:"name:world" description:"Limit one greeting per person" >
+exit status 1
+```
+
+[status]:       https://godoc.org/google.golang.org/grpc/status#Status
+[new-status]:   https://godoc.org/google.golang.org/grpc/status#New
+[code]:         https://godoc.org/google.golang.org/grpc/codes#Code
+[with-details]: https://godoc.org/google.golang.org/grpc/status#Status.WithDetails
+[details]:      https://godoc.org/google.golang.org/grpc/status#Status.Details
+[status-err]:   https://godoc.org/google.golang.org/grpc/status#Status.Err
+[status-error]: https://godoc.org/google.golang.org/grpc/status#Error
+[example]:      https://github.com/grpc/grpc-go/blob/master/examples/rpc_errors

vendor/google.golang.org/grpc/Documentation/server-reflection-tutorial.md

@@ -0,0 +1,152 @@
+# gRPC Server Reflection Tutorial
+
+gRPC Server Reflection provides information about publicly-accessible gRPC
+services on a server, and assists clients at runtime to construct RPC
+requests and responses without precompiled service information. It is used by
+gRPC CLI, which can be used to introspect server protos and send/receive test
+RPCs.
+
+## Enable Server Reflection
+
+gRPC-go Server Reflection is implemented in package [reflection](https://github.com/grpc/grpc-go/tree/master/reflection). To enable server reflection, you need to import this package and register reflection service on your gRPC server.
+
+For example, to enable server reflection in `example/helloworld`, we need to make the following changes:
+
+```diff
+--- a/examples/helloworld/greeter_server/main.go
++++ b/examples/helloworld/greeter_server/main.go
+@@ -40,6 +40,7 @@ import (
+        "golang.org/x/net/context"
+        "google.golang.org/grpc"
+        pb "google.golang.org/grpc/examples/helloworld/helloworld"
++       "google.golang.org/grpc/reflection"
+ )
+
+ const (
+@@ -61,6 +62,8 @@ func main() {
+        }
+        s := grpc.NewServer()
+        pb.RegisterGreeterServer(s, &server{})
++       // Register reflection service on gRPC server.
++       reflection.Register(s)
+        if err := s.Serve(lis); err != nil {
+                log.Fatalf("failed to serve: %v", err)
+        }
+```
+
+We have made this change in `example/helloworld`, and we will use it as an example to show the use of gRPC server reflection and gRPC CLI in this tutorial.
+
+## gRPC CLI
+
+After enabling Server Reflection in a server application, you can use gRPC CLI to check its services.
+gRPC CLI is only available in c++. Instructions on how to use gRPC CLI can be found at [command_line_tool.md](https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md).
+
+To build gRPC CLI:
+
+```sh
+git clone https://github.com/grpc/grpc
+cd grpc
+make grpc_cli
+cd bins/opt # grpc_cli is in directory bins/opt/
+```
+
+## Use gRPC CLI to check services
+
+First, start the helloworld server in grpc-go directory:
+
+```sh
+$ cd <grpc-go-directory>
+$ go run examples/helloworld/greeter_server/main.go
+```
+
+Open a new terminal and make sure you are in the directory where grpc_cli lives:
+
+```sh
+$ cd <grpc-cpp-dirctory>/bins/opt
+```
+
+### List services
+
+`grpc_cli ls` command lists services and methods exposed at a given port:
+
+- List all the services exposed at a given port
+
+  ```sh
+  $ ./grpc_cli ls localhost:50051
+  ```
+
+  output:
+  ```sh
+  helloworld.Greeter
+  grpc.reflection.v1alpha.ServerReflection
+  ```
+
+- List one service with details
+
+  `grpc_cli ls` command inspects a service given its full name (in the format of
+  \<package\>.\<service\>). It can print information with a long listing format
+  when `-l` flag is set. This flag can be used to get more details about a
+  service.
+
+  ```sh
+  $ ./grpc_cli ls localhost:50051 helloworld.Greeter -l
+  ```
+
+  output:
+  ```sh
+  filename: helloworld.proto
+  package: helloworld;
+  service Greeter {
+    rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
+  }
+
+  ```
+
+### List methods
+
+- List one method with details
+
+  `grpc_cli ls` command also inspects a method given its full name (in the
+  format of \<package\>.\<service\>.\<method\>).
+
+  ```sh
+  $ ./grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l
+  ```
+
+  output:
+  ```sh
+    rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
+  ```
+
+### Inspect message types
+
+We can use`grpc_cli type` command to inspect request/response types given the
+full name of the type (in the format of \<package\>.\<type\>).
+
+- Get information about the request type
+
+  ```sh
+  $ ./grpc_cli type localhost:50051 helloworld.HelloRequest
+  ```
+
+  output:
+  ```sh
+  message HelloRequest {
+    optional string name = 1[json_name = "name"];
+  }
+  ```
+
+### Call a remote method
+
+We can send RPCs to a server and get responses using `grpc_cli call` command.
+
+- Call a unary method
+
+  ```sh
+  $ ./grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'"
+  ```
+
+  output:
+  ```sh
+  message: "Hello gRPC CLI"
+  ```

vendor/google.golang.org/grpc/Documentation/versioning.md

@@ -0,0 +1,34 @@
+# Versioning and Releases
+
+Note: This document references terminology defined at http://semver.org.
+
+## Release Frequency
+
+Regular MINOR releases of gRPC-Go are performed every six weeks.  Patch releases
+to the previous two MINOR releases may be performed on demand or if serious
+security problems are discovered.
+
+## Versioning Policy
+
+The gRPC-Go versioning policy follows the Semantic Versioning 2.0.0
+specification, with the following exceptions:
+
+- A MINOR version will not _necessarily_ add new functionality.
+
+- MINOR releases will not break backward compatibility, except in the following
+circumstances:
+
+  - An API was marked as EXPERIMENTAL upon its introduction.
+  - An API was marked as DEPRECATED in the initial MAJOR release.
+  - An API is inherently flawed and cannot provide correct or secure behavior.
+
+  In these cases, APIs MAY be changed or removed without a MAJOR release.
+Otherwise, backward compatibility will be preserved by MINOR releases.
+
+  For an API marked as DEPRECATED, an alternative will be available (if
+appropriate) for at least three months prior to its removal.
+
+## Release History
+
+Please see our release history on GitHub:
+https://github.com/grpc/grpc-go/releases