vendor files

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/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,41 @@
+# 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)
+```
+
+# 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,204 @@
+# 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
+
+To send metadata to server, the client can wrap the metadata into a context using `NewOutgoingContext`, and make the RPC with this context:
+
+```go
+md := metadata.Pairs("key", "val")
+
+// create a new context with this metadata
+ctx := metadata.NewOutgoingContext(context.Background(), md)
+
+// make unary RPC
+response, err := client.SomeRPC(ctx, someRequest)
+
+// or make streaming RPC
+stream, err := client.SomeStreamingRPC(ctx)
+```
+
+To read this back from the context on the client (e.g. in an interceptor) before the RPC is sent, use `FromOutgoingContext`.
+
+### 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/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