examples: add new example to show updating metadata in interceptors

Documentation/grpc-metadata.md

@@ -223,3 +223,49 @@ func (s *server) SomeStreamingRPC(stream pb.Service_SomeStreamingRPCServer) erro
     stream.SetTrailer(trailer)
 }
 ```
+
+## Updating metadata in the interceptor - server side
+
+Server side metadata updating in the interceptor examples are available [here](../examples/features/metadata_interceptor/server/main.go).
+
+#### Unary interceptor
+
+To read and update metadata in the interceptor under unary call, the server needs to retrieve it from RPC context and update it through this RPC context.
+
+```go
+func SomeInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
+	// get the metadata from context
+	md, ok := metadata.FromIncomingContext(ctx)
+
+	// update metadata
+	md.Append("key1", "value1")
+
+	// set the metadata to context
+	ctx = metadata.NewIncomingContext(ctx, md)
+```
+
+#### Streaming interceptor
+
+Since there is no direct way to set RPC context in the stream interceptor, the `wrappedStream` could be created and override `Context()` method with owned `context`. Then pass this `wrappedStream` to the stream interceptor.
+
+```go
+type wrappedStream struct {
+	grpc.ServerStream
+	ctx context.Context
+}
+
+func (s *wrappedStream) Context() context.Context {
+	return s.ctx
+}
+
+func streamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
+	// get the metadata from context
+	md, ok := metadata.FromIncomingContext(ss.Context())
+	// update metadata
+	md.Append("key1", "value1")
+	// set the metadata to context
+	ctx := metadata.NewIncomingContext(ss.Context(), md)
+
+	return handler(srv, &wrappedStream{ss, ctx})
+}
+```

examples/features/metadata/server/main.go

@@ -31,10 +31,9 @@ import (
 
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/codes"
+	pb "google.golang.org/grpc/examples/features/proto/echo"
 	"google.golang.org/grpc/metadata"
 	"google.golang.org/grpc/status"
-
-	pb "google.golang.org/grpc/examples/features/proto/echo"
 )
 
 var port = flag.Int("port", 50051, "the port to serve on")

examples/features/metadata_interceptor/README.md

@@ -0,0 +1,18 @@
+# Metadata interceptor example
+
+This example shows how to update metadata in RPC unary interceptor and streaming interceptor.
+Please see
+[grpc-metadata.md](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md)
+for more information.
+
+## Start the server
+
+```
+go run server/main.go
+```
+
+## Run the client
+
+```
+go run client/main.go
+```

examples/features/metadata_interceptor/client/main.go

@@ -0,0 +1,90 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Binary client is an example client.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"time"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	pb "google.golang.org/grpc/examples/features/proto/echo"
+)
+
+var addr = flag.String("addr", "localhost:50051", "the address to connect to")
+
+const message = "hello world"
+
+func callUnaryEcho(client pb.EchoClient, message string) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	resp, err := client.UnaryEcho(ctx, &pb.EchoRequest{Message: message})
+	if err != nil {
+		log.Fatalf("client.UnaryEcho(_) = _, %v: ", err)
+	}
+	fmt.Println("UnaryEcho: ", resp.Message)
+}
+
+func callBidiStreamingEcho(client pb.EchoClient, message string) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	c, err := client.BidirectionalStreamingEcho(ctx)
+	if err != nil {
+		return
+	}
+
+	if err := c.Send(&pb.EchoRequest{Message: message}); err != nil {
+		log.Fatalf("failed to send request due to error: %v", err)
+	}
+	c.CloseSend()
+
+	for {
+		resp, err := c.Recv()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			log.Fatalf("failed to receive response due to error: %v", err)
+		}
+		fmt.Println("BidiStreaming Echo: ", resp.Message)
+	}
+}
+
+func main() {
+	flag.Parse()
+	// Set up a connection to the server.
+	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		log.Fatalf("did not connect: %v", err)
+	}
+	defer conn.Close()
+
+	ec := pb.NewEchoClient(conn)
+
+	callUnaryEcho(ec, message)
+	time.Sleep(1 * time.Second)
+
+	callBidiStreamingEcho(ec, message)
+}

examples/features/metadata_interceptor/server/main.go

@@ -0,0 +1,147 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Binary server is an example server.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"math/rand"
+	"net"
+	"time"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	pb "google.golang.org/grpc/examples/features/proto/echo"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/status"
+)
+
+var port = flag.Int("port", 50051, "the port to serve on")
+
+var errMissingMetadata = status.Errorf(codes.InvalidArgument, "missing metadata")
+
+type server struct {
+	pb.UnimplementedEchoServer
+}
+
+func unaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
+	md, ok := metadata.FromIncomingContext(ctx)
+	if !ok {
+		return nil, errMissingMetadata
+	}
+
+	md.Append("key1", "value1")
+	ctx = metadata.NewIncomingContext(ctx, md)
+
+	return handler(ctx, req)
+}
+
+func (s *server) UnaryEcho(ctx context.Context, in *pb.EchoRequest) (*pb.EchoResponse, error) {
+	fmt.Printf("--- UnaryEcho ---\n")
+
+	md, ok := metadata.FromIncomingContext(ctx)
+	if !ok {
+		return nil, status.Errorf(codes.DataLoss, "UnaryEcho: failed to get metadata")
+	}
+
+	// Read metadata from interceptor
+	if v, ok := md["key1"]; ok {
+		fmt.Printf("key1 from metadata: \n")
+		for i, e := range v {
+			fmt.Printf(" %d. %s\n", i, e)
+		}
+	}
+
+	fmt.Printf("request received: %v, sending echo\n", in)
+
+	return &pb.EchoResponse{Message: in.Message}, nil
+}
+
+type wrappedStream struct {
+	grpc.ServerStream
+	ctx context.Context
+}
+
+func (s *wrappedStream) Context() context.Context {
+	return s.ctx
+}
+
+func streamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
+	md, ok := metadata.FromIncomingContext(ss.Context())
+	if !ok {
+		return errMissingMetadata
+	}
+
+	md.Append("key1", "value1")
+	ctx := metadata.NewIncomingContext(ss.Context(), md)
+
+	return handler(srv, &wrappedStream{ss, ctx})
+}
+
+func (s *server) BidirectionalStreamingEcho(stream pb.Echo_BidirectionalStreamingEchoServer) error {
+	fmt.Printf("--- BidirectionalStreamingEcho ---\n")
+
+	md, ok := metadata.FromIncomingContext(stream.Context())
+	if !ok {
+		return status.Errorf(codes.DataLoss, "BidirectionalStreamingEcho: failed to get metadata")
+	}
+
+	// Read metadata from interceptor.
+	if v, ok := md["key1"]; ok {
+		fmt.Printf("key1 from metadata: \n")
+		for i, e := range v {
+			fmt.Printf(" %d. %s\n", i, e)
+		}
+	}
+
+	// Read requests and send responses.
+	for {
+		in, err := stream.Recv()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		fmt.Printf("request received %v, sending echo\n", in)
+		if err := stream.Send(&pb.EchoResponse{Message: in.Message}); err != nil {
+			return err
+		}
+	}
+}
+
+func main() {
+	flag.Parse()
+	rand.Seed(time.Now().UnixNano())
+	lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
+	if err != nil {
+		log.Fatalf("failed to listen: %v", err)
+	}
+	fmt.Printf("server listening at %v\n", lis.Addr())
+
+	s := grpc.NewServer(
+		grpc.UnaryInterceptor(unaryInterceptor),
+		grpc.StreamInterceptor(streamInterceptor))
+	pb.RegisterEchoServer(s, &server{})
+	s.Serve(lis)
+}