Merge pull request go-kit#287 from go-kit/addsvc-errors

examples/addsvc: more sophisticated error encoding

Author: peterbourgon

examples/addsvc/endpoints.go

@@ -42,7 +42,7 @@ func (e Endpoints) Sum(ctx context.Context, a, b int) (int, error) {
 	if err != nil {
 		return 0, err
 	}
-	return response.(sumResponse).V, nil
+	return response.(sumResponse).V, response.(sumResponse).Err
 }
 
 // Concat implements Service. Primarily useful in a client.
@@ -52,7 +52,7 @@ func (e Endpoints) Concat(ctx context.Context, a, b string) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	return response.(concatResponse).V, err
+	return response.(concatResponse).V, response.(concatResponse).Err
 }
 
 // MakeSumEndpoint returns an endpoint that invokes Sum on the service.
@@ -61,11 +61,12 @@ func MakeSumEndpoint(s Service) endpoint.Endpoint {
 	return func(ctx context.Context, request interface{}) (response interface{}, err error) {
 		sumReq := request.(sumRequest)
 		v, err := s.Sum(ctx, sumReq.A, sumReq.B)
-		if err != nil {
-			return nil, err
+		if err == ErrIntOverflow {
+			return nil, err // special case; see comment on ErrIntOverflow
 		}
 		return sumResponse{
-			V: v,
+			V:   v,
+			Err: err,
 		}, nil
 	}
 }
@@ -76,11 +77,9 @@ func MakeConcatEndpoint(s Service) endpoint.Endpoint {
 	return func(ctx context.Context, request interface{}) (response interface{}, err error) {
 		concatReq := request.(concatRequest)
 		v, err := s.Concat(ctx, concatReq.A, concatReq.B)
-		if err != nil {
-			return nil, err
-		}
 		return concatResponse{
-			V: v,
+			V:   v,
+			Err: err,
 		}, nil
 	}
 }
@@ -124,8 +123,14 @@ func EndpointLoggingMiddleware(logger log.Logger) endpoint.Middleware {
 
 type sumRequest struct{ A, B int }
 
-type sumResponse struct{ V int }
+type sumResponse struct {
+	V   int
+	Err error
+}
 
 type concatRequest struct{ A, B string }
 
-type concatResponse struct{ V string }
+type concatResponse struct {
+	V   string
+	Err error
+}

examples/addsvc/pb/addsvc.pb.go

@@ -20,6 +20,7 @@ message SumRequest {
 // The sum response contains the result of the calculation.
 message SumReply {
   int64 v = 1;
+  string err = 2;
 }
 
 // The Concat request contains two parameters.
@@ -31,4 +32,5 @@ message ConcatRequest {
 // The Concat response contains the result of the concatenation.
 message ConcatReply {
   string v = 1;
+  string err = 2;
 }

examples/addsvc/pb/addsvc.proto

@@ -19,17 +19,46 @@ type Service interface {
 	Concat(ctx context.Context, a, b string) (string, error)
 }
 
+// Business-domain errors like these may be served in two ways: returned
+// directly by endpoints, or bundled into the response struct. Both methods can
+// be made to work, but errors returned directly by endpoints are counted by
+// middlewares that check errors, like circuit breakers.
+//
+// If you don't want that behavior -- and you probably don't -- then it's better
+// to bundle errors into the response struct.
+
 var (
 	// ErrTwoZeroes is an arbitrary business rule for the Add method.
 	ErrTwoZeroes = errors.New("can't sum two zeroes")
 
-	// ErrIntOverflow protects the Add method.
+	// ErrIntOverflow protects the Add method. We've decided that this error
+	// indicates a misbehaving service and should count against e.g. circuit
+	// breakers. So, we return it directly in endpoints, to illustrate the
+	// difference. In a real service, this probably wouldn't be the case.
 	ErrIntOverflow = errors.New("integer overflow")
 
 	// ErrMaxSizeExceeded protects the Concat method.
 	ErrMaxSizeExceeded = errors.New("result exceeds maximum size")
 )
 
+// These annoying helper functions are required to translate Go error types to
+// and from strings, which is the type we use in our IDLs to represent errors.
+// There is special casing to treat empty strings as nil errors.
+
+func str2err(s string) error {
+	if s == "" {
+		return nil
+	}
+	return errors.New(s)
+}
+
+func err2str(err error) string {
+	if err == nil {
+		return ""
+	}
+	return err.Error()
+}
+
 // NewBasicService returns a naïve, stateless implementation of Service.
 func NewBasicService() Service {
 	return basicService{}

examples/addsvc/service.go

@@ -1,9 +1,11 @@
 struct SumReply {
 	1: i64 value
+	2: string err
 }
 
 struct ConcatReply {
 	1: string value
+	2: string err
 }
 
 service AddService {

examples/addsvc/thrift/addsvc.thrift

@@ -76,30 +76,30 @@ func DecodeGRPCConcatRequest(_ context.Context, grpcReq interface{}) (interface{
 // gRPC sum reply to a user-domain sum response. Primarily useful in a client.
 func DecodeGRPCSumResponse(_ context.Context, grpcReply interface{}) (interface{}, error) {
 	reply := grpcReply.(*pb.SumReply)
-	return sumResponse{V: int(reply.V)}, nil
+	return sumResponse{V: int(reply.V), Err: str2err(reply.Err)}, nil
 }
 
 // DecodeGRPCConcatResponse is a transport/grpc.DecodeResponseFunc that converts
 // a gRPC concat reply to a user-domain concat response. Primarily useful in a
 // client.
 func DecodeGRPCConcatResponse(_ context.Context, grpcReply interface{}) (interface{}, error) {
 	reply := grpcReply.(*pb.ConcatReply)
-	return concatResponse{V: reply.V}, nil
+	return concatResponse{V: reply.V, Err: str2err(reply.Err)}, nil
 }
 
 // EncodeGRPCSumResponse is a transport/grpc.EncodeResponseFunc that converts a
 // user-domain sum response to a gRPC sum reply. Primarily useful in a server.
 func EncodeGRPCSumResponse(_ context.Context, response interface{}) (interface{}, error) {
 	resp := response.(sumResponse)
-	return &pb.SumReply{V: int64(resp.V)}, nil
+	return &pb.SumReply{V: int64(resp.V), Err: err2str(resp.Err)}, nil
 }
 
 // EncodeGRPCConcatResponse is a transport/grpc.EncodeResponseFunc that converts
 // a user-domain concat response to a gRPC concat reply. Primarily useful in a
 // server.
 func EncodeGRPCConcatResponse(_ context.Context, response interface{}) (interface{}, error) {
 	resp := response.(concatResponse)
-	return &pb.ConcatReply{V: resp.V}, nil
+	return &pb.ConcatReply{V: resp.V, Err: err2str(resp.Err)}, nil
 }
 
 // EncodeGRPCSumRequest is a transport/grpc.EncodeRequestFunc that converts a