Add status package for reporting gRPC status and errors (#1156)

When an error implemented by the status package is returned from a service
handler, the server will transmit a rich status message in the
"grpc-status-details-bin" trailing metadata field if any detailed data is
attached to the error.  Client-side, we will decode them if present in the
server's response and return them to the user code performing the RPC.

This is backward compatible with the existing errors supported by the grpc
package.  However, the grpc.Errorf, grpc.Code and grpc.ErrorDesc functions for
managing errors are now deprecated; status.Errorf and status.Status type
asserions should be used instead.

call.go

@@ -43,6 +43,7 @@ import (
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/peer"
 	"google.golang.org/grpc/stats"
+	"google.golang.org/grpc/status"
 	"google.golang.org/grpc/transport"
 )
 
@@ -79,7 +80,7 @@ func recvResponse(ctx context.Context, dopts dialOptions, t transport.ClientTran
 			return
 		}
 	}
-	if inPayload != nil && err == io.EOF && stream.StatusCode() == codes.OK {
+	if inPayload != nil && err == io.EOF && stream.Status().Code() == codes.OK {
 		// TODO in the current implementation, inTrailer may be handled before inPayload in some cases.
 		// Fix the order if necessary.
 		dopts.copts.StatsHandler.HandleRPC(ctx, inPayload)
@@ -230,7 +231,7 @@ func invoke(ctx context.Context, method string, args, reply interface{}, cc *Cli
 		t, put, err = cc.getTransport(ctx, gopts)
 		if err != nil {
 			// TODO(zhaoq): Probably revisit the error handling.
-			if _, ok := err.(*rpcError); ok {
+			if _, ok := err.(status.Status); ok {
 				return err
 			}
 			if err == errConnClosing || err == errConnUnavailable {
@@ -284,6 +285,6 @@ func invoke(ctx context.Context, method string, args, reply interface{}, cc *Cli
 			put()
 			put = nil
 		}
-		return Errorf(stream.StatusCode(), "%s", stream.StatusDesc())
+		return stream.Status().Err()
 	}
 }

call_test.go

@@ -46,6 +46,7 @@ import (
 
 	"golang.org/x/net/context"
 	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 	"google.golang.org/grpc/transport"
 )
 
@@ -99,21 +100,21 @@ func (h *testStreamHandler) handleStream(t *testing.T, s *transport.Stream) {
 			return
 		}
 		if v == "weird error" {
-			h.t.WriteStatus(s, codes.Internal, weirdError)
+			h.t.WriteStatus(s, status.New(codes.Internal, weirdError))
 			return
 		}
 		if v == "canceled" {
 			canceled++
-			h.t.WriteStatus(s, codes.Internal, "")
+			h.t.WriteStatus(s, status.New(codes.Internal, ""))
 			return
 		}
 		if v == "port" {
-			h.t.WriteStatus(s, codes.Internal, h.port)
+			h.t.WriteStatus(s, status.New(codes.Internal, h.port))
 			return
 		}
 
 		if v != expectedRequest {
-			h.t.WriteStatus(s, codes.Internal, strings.Repeat("A", sizeLargeErr))
+			h.t.WriteStatus(s, status.New(codes.Internal, strings.Repeat("A", sizeLargeErr)))
 			return
 		}
 	}
@@ -124,7 +125,7 @@ func (h *testStreamHandler) handleStream(t *testing.T, s *transport.Stream) {
 		return
 	}
 	h.t.Write(s, reply, &transport.Options{})
-	h.t.WriteStatus(s, codes.OK, "")
+	h.t.WriteStatus(s, status.New(codes.OK, ""))
 }
 
 type server struct {
@@ -239,7 +240,7 @@ func TestInvokeLargeErr(t *testing.T) {
 	var reply string
 	req := "hello"
 	err := Invoke(context.Background(), "/foo/bar", &req, &reply, cc)
-	if _, ok := err.(*rpcError); !ok {
+	if _, ok := err.(status.Status); !ok {
 		t.Fatalf("grpc.Invoke(_, _, _, _, _) receives non rpc error.")
 	}
 	if Code(err) != codes.Internal || len(ErrorDesc(err)) != sizeLargeErr {
@@ -255,7 +256,7 @@ func TestInvokeErrorSpecialChars(t *testing.T) {
 	var reply string
 	req := "weird error"
 	err := Invoke(context.Background(), "/foo/bar", &req, &reply, cc)
-	if _, ok := err.(*rpcError); !ok {
+	if _, ok := err.(status.Status); !ok {
 		t.Fatalf("grpc.Invoke(_, _, _, _, _) receives non rpc error.")
 	}
 	if got, want := ErrorDesc(err), weirdError; got != want {

rpc_util.go

@@ -37,7 +37,6 @@ import (
 	"bytes"
 	"compress/gzip"
 	"encoding/binary"
-	"fmt"
 	"io"
 	"io/ioutil"
 	"math"
@@ -50,6 +49,7 @@ import (
 	"google.golang.org/grpc/metadata"
 	"google.golang.org/grpc/peer"
 	"google.golang.org/grpc/stats"
+	"google.golang.org/grpc/status"
 	"google.golang.org/grpc/transport"
 )
 
@@ -372,88 +372,56 @@ func recv(p *parser, c Codec, s *transport.Stream, dc Decompressor, m interface{
 	return nil
 }
 
-// rpcError defines the status from an RPC.
-type rpcError struct {
-	code codes.Code
-	desc string
-}
-
-func (e *rpcError) Error() string {
-	return fmt.Sprintf("rpc error: code = %s desc = %s", e.code, e.desc)
-}
-
 // Code returns the error code for err if it was produced by the rpc system.
 // Otherwise, it returns codes.Unknown.
+//
+// Deprecated; use status.FromError and Code method instead.
 func Code(err error) codes.Code {
-	if err == nil {
-		return codes.OK
-	}
-	if e, ok := err.(*rpcError); ok {
-		return e.code
+	if s, ok := status.FromError(err); ok {
+		return s.Code()
 	}
 	return codes.Unknown
 }
 
 // ErrorDesc returns the error description of err if it was produced by the rpc system.
 // Otherwise, it returns err.Error() or empty string when err is nil.
+//
+// Deprecated; use status.FromError and Message method instead.
 func ErrorDesc(err error) string {
-	if err == nil {
-		return ""
-	}
-	if e, ok := err.(*rpcError); ok {
-		return e.desc
+	if s, ok := status.FromError(err); ok {
+		return s.Message()
 	}
 	return err.Error()
 }
 
 // Errorf returns an error containing an error code and a description;
 // Errorf returns nil if c is OK.
+//
+// Deprecated; use status.Errorf instead.
 func Errorf(c codes.Code, format string, a ...interface{}) error {
-	if c == codes.OK {
-		return nil
-	}
-	return &rpcError{
-		code: c,
-		desc: fmt.Sprintf(format, a...),
-	}
+	return status.Errorf(c, format, a...)
 }
 
-// toRPCErr converts an error into a rpcError.
+// toRPCErr converts an error into an error from the status package.
 func toRPCErr(err error) error {
 	switch e := err.(type) {
-	case *rpcError:
+	case status.Status:
 		return err
 	case transport.StreamError:
-		return &rpcError{
-			code: e.Code,
-			desc: e.Desc,
-		}
+		return status.Error(e.Code, e.Desc)
 	case transport.ConnectionError:
-		return &rpcError{
-			code: codes.Internal,
-			desc: e.Desc,
-		}
+		return status.Error(codes.Internal, e.Desc)
 	default:
 		switch err {
 		case context.DeadlineExceeded:
-			return &rpcError{
-				code: codes.DeadlineExceeded,
-				desc: err.Error(),
-			}
+			return status.Error(codes.DeadlineExceeded, err.Error())
 		case context.Canceled:
-			return &rpcError{
-				code: codes.Canceled,
-				desc: err.Error(),
-			}
+			return status.Error(codes.Canceled, err.Error())
 		case ErrClientConnClosing:
-			return &rpcError{
-				code: codes.FailedPrecondition,
-				desc: err.Error(),
-			}
+			return status.Error(codes.FailedPrecondition, err.Error())
 		}
-
 	}
-	return Errorf(codes.Unknown, "%v", err)
+	return status.Error(codes.Unknown, err.Error())
 }
 
 // convertCode converts a standard Go error into its canonical code. Note that

rpc_util_test.go

@@ -41,8 +41,8 @@ import (
 	"testing"
 
 	"github.com/golang/protobuf/proto"
-	"golang.org/x/net/context"
 	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 	perfpb "google.golang.org/grpc/test/codec_perf"
 	"google.golang.org/grpc/transport"
 )
@@ -150,51 +150,21 @@ func TestToRPCErr(t *testing.T) {
 		// input
 		errIn error
 		// outputs
-		errOut *rpcError
+		errOut error
 	}{
-		{transport.StreamError{codes.Unknown, ""}, Errorf(codes.Unknown, "").(*rpcError)},
-		{transport.ErrConnClosing, Errorf(codes.Internal, transport.ErrConnClosing.Desc).(*rpcError)},
+		{transport.StreamError{Code: codes.Unknown, Desc: ""}, status.Error(codes.Unknown, "")},
+		{transport.ErrConnClosing, status.Error(codes.Internal, transport.ErrConnClosing.Desc)},
 	} {
 		err := toRPCErr(test.errIn)
-		rpcErr, ok := err.(*rpcError)
-		if !ok {
-			t.Fatalf("toRPCErr{%v} returned type %T, want %T", test.errIn, err, rpcError{})
+		if _, ok := err.(status.Status); !ok {
+			t.Fatalf("toRPCErr{%v} returned type %T, want %T", test.errIn, err, status.Error(codes.Unknown, ""))
 		}
-		if *rpcErr != *test.errOut {
+		if !reflect.DeepEqual(err, test.errOut) {
 			t.Fatalf("toRPCErr{%v} = %v \nwant %v", test.errIn, err, test.errOut)
 		}
 	}
 }
 
-func TestContextErr(t *testing.T) {
-	for _, test := range []struct {
-		// input
-		errIn error
-		// outputs
-		errOut transport.StreamError
-	}{
-		{context.DeadlineExceeded, transport.StreamError{codes.DeadlineExceeded, context.DeadlineExceeded.Error()}},
-		{context.Canceled, transport.StreamError{codes.Canceled, context.Canceled.Error()}},
-	} {
-		err := transport.ContextErr(test.errIn)
-		if err != test.errOut {
-			t.Fatalf("ContextErr{%v} = %v \nwant %v", test.errIn, err, test.errOut)
-		}
-	}
-}
-
-func TestErrorsWithSameParameters(t *testing.T) {
-	const description = "some description"
-	e1 := Errorf(codes.AlreadyExists, description).(*rpcError)
-	e2 := Errorf(codes.AlreadyExists, description).(*rpcError)
-	if e1 == e2 {
-		t.Fatalf("Error interfaces should not be considered equal - e1: %p - %v  e2: %p - %v", e1, e1, e2, e2)
-	}
-	if Code(e1) != Code(e2) || ErrorDesc(e1) != ErrorDesc(e2) {
-		t.Fatalf("Expected errors to have same code and description - e1: %p - %v  e2: %p - %v", e1, e1, e2, e2)
-	}
-}
-
 // bmEncode benchmarks encoding a Protocol Buffer message containing mSize
 // bytes.
 func bmEncode(b *testing.B, mSize int) {