update error codes, api and finalize implementation

Author: ettec

pkg/capabilities/errors/error.go

@@ -2,70 +2,147 @@ package errors
 
 import "fmt"
 
-type ReportType int
+type Origin int
 
 const (
-	// LocalOnly The message in the error may contain sensitive node local information and should not be reported remotely.
-	// In addition the serialised string representation is prefixed with an identify that prevents the error
-	// from being accidentally or maliciously marked as remote reportable by manipulating the error string.
-	LocalOnly ReportType = 0
+	// OriginSystem The error originated from a system issue.
+	OriginSystem = 0
 
-	// RemoteReportable The message in the error is safe to report remotely between nodes.
-	RemoteReportable ReportType = 1
+	// OriginUser The error originated from user input or action.
+	OriginUser = 1
+)
+
+func (o Origin) String() string {
+	switch o {
+	case OriginSystem:
+		return "System"
+	case OriginUser:
+		return "User"
+	default:
+		return "Unknown"
+	}
+}
 
-	// ReportableUser The error is due to user error and is safe to report remotely between nodes.
-	ReportableUser ReportType = 2
+// FromOriginString converts a string to an Origin value.
+func FromOriginString(s string) Origin {
+	switch s {
+	case "System":
+		return OriginSystem
+	case "User":
+		return OriginUser
+	default:
+		return Origin(-1)
+	}
+}
+
+type Visibility int
+
+const (
+	// VisibilityPublic The full details of the error can be shared across all nodes in the network.
+	VisibilityPublic = 0
+
+	// VisibilityPrivate The error contains sensitive information that should only be visible to the local node.
+	VisibilityPrivate = 1
 )
 
+// String returns the string representation of the Visibility value.
+func (v Visibility) String() string {
+	switch v {
+	case VisibilityPublic:
+		return "Public"
+	case VisibilityPrivate:
+		return "Private"
+	default:
+		return "Unknown"
+	}
+}
+
+// FromVisibilityString converts a string to a Visibility value.
+func FromVisibilityString(s string) Visibility {
+	switch s {
+	case "Public":
+		return VisibilityPublic
+	case "Private":
+		return VisibilityPrivate
+	default:
+		return Visibility(-1)
+	}
+}
+
 type Error interface {
 	error
 
-	ReportType() ReportType
+	Visibility() Visibility
+	Origin() Origin
 	Code() ErrorCode
 	SerializeToString() string
 	SerializeToRemoteReportableString() string
+	Equals(otherErr Error) bool
 }
 
 type capabilityError struct {
 	err        error
-	reportType ReportType
+	origin     Origin
+	visibility Visibility
 	errorCode  ErrorCode
 }
 
-func newError(err error, reportType ReportType, errorCode ErrorCode) Error {
+func NewError(err error, visibility Visibility, origin Origin, errorCode ErrorCode) Error {
 	return &capabilityError{
 		err:        err,
-		reportType: reportType,
+		origin:     origin,
+		visibility: visibility,
 		errorCode:  errorCode,
 	}
 }
 
-// NewRemoteReportableError indicates that the wrapped error does not contain any node local confidential information
-// and is safe to report to other nodes in the network.
-func NewRemoteReportableError(err error, errorCode ErrorCode) Error {
-	return newError(err, RemoteReportable, errorCode)
+// NewPublicSystemError indicates that the wrapped error is due to a system-level issue and does not contain any
+// sensitive information that should only be visible to the node on which it occurred, making it safe to share the full error details
+// with other nodes in the network.
+func NewPublicSystemError(err error, errorCode ErrorCode) Error {
+	return NewError(err, VisibilityPublic, OriginSystem, errorCode)
 }
 
-// NewReportableUserError indicates that the wrapped error is due to user error and does not contain any node local confidential information
-// and is safe to report to other nodes in the network.
-func NewReportableUserError(err error, errorCode ErrorCode) Error {
-	return newError(err, ReportableUser, errorCode)
+// NewPublicUserError indicates that the wrapped error is due to a user-level issue and does not contain any
+// information that should only be visible to the node on which it occurred, making it safe to share the full error details
+// with other nodes in the network.
+func NewPublicUserError(err error, errorCode ErrorCode) Error {
+	return NewError(err, VisibilityPublic, OriginUser, errorCode)
 }
 
-// NewLocalReportableError indicates that the wrapped error may contain node local confidential information
-// that should not be reported to other nodes in the network.  Only the error code and generic message will be reported remotely.
-func NewLocalReportableError(err error, errorCode ErrorCode) Error {
-	return newError(err, LocalOnly, errorCode)
+// NewPrivateSystemError indicates that the wrapped error is due to a system-level issue and may contain
+// sensitive information that should only be visible to the node on which it occurred.  The error code will still be
+// visible to other nodes in the network.
+func NewPrivateSystemError(err error, errorCode ErrorCode) Error {
+	return NewError(err, VisibilityPrivate, OriginSystem, errorCode)
 }
 
-func (e *capabilityError) Error() string {
+// NewPrivateUserError indicates that the wrapped error is due to a user-level issue and may contain
+// sensitive information that should only be visible to the node on which it occurred.  The error code will still be
+// visible to other nodes in the network.
+func NewPrivateUserError(err error, errorCode ErrorCode) Error {
+	return NewError(err, VisibilityPrivate, OriginSystem, errorCode)
+}
+
+func (e capabilityError) Error() string {
 	return fmt.Sprintf("[%d]%s:", e.errorCode, e.errorCode.String()) + " " + e.err.Error()
 }
 
-func (e *capabilityError) ReportType() ReportType {
-	return e.reportType
+func (e capabilityError) Origin() Origin {
+	return e.origin
+}
+
+func (e capabilityError) Visibility() Visibility {
+	return e.visibility
 }
 
-func (e *capabilityError) Code() ErrorCode {
+func (e capabilityError) Code() ErrorCode {
 	return e.errorCode
 }
+
+func (e capabilityError) Equals(otherErr Error) bool {
+	return e.errorCode == otherErr.Code() &&
+		e.origin == otherErr.Origin() &&
+		e.visibility == otherErr.Visibility() &&
+		e.Error() == otherErr.Error()
+}

pkg/capabilities/errors/error_codes.go

@@ -2,49 +2,54 @@ package errors
 
 type ErrorCode uint32
 
-// *** TODO ***
-// Just use GRPC error codes? or use GRPC error codes as inspiration (as below) but customize
-// to make them relevant to capabilities?, IMO latter is better as it gives the flexibility to add
-// more capability specific error codes (e.g. ConsensusFailed) whilst removing those
-// that are not relevant (e.g OK, Unknown,
-
+// Capability error codes. These are largely based on gRPC error codes:
+// https://grpc.github.io/grpc/core/md_doc_statuscodes.html.  Additional
+// custom error codes can be added starting from 100 to avoid collision with
+// future gRPC defined codes.  0 (OK) is excluded is it is never a valid code for
+// a capability error as capability errors must always represent some failure condition.
 const (
-	// Uncategorized indicates no appropriate error code available - the capability author should consider adding a
-	// code that fits better.  If the error code does not exist on the receiving side, it will be treated as Uncategorized
-	// to ensure backwards compatibility.
-	Uncategorized ErrorCode = 0
+	// Canceled indicates the operation was canceled (typically by the caller).
+	Canceled ErrorCode = 1
 
-	// Cancelled indicates the operation was canceled (typically by the caller).
-	Cancelled ErrorCode = 1
+	// Unknown error. An example of where this error may be returned is
+	// if a Status value received from another address space belongs to
+	// an error-space that is not known in this address space. Also
+	// errors raised by APIs that do not return enough error information
+	// may be converted to this error.
+	Unknown ErrorCode = 2
 
 	// InvalidArgument indicates client specified an invalid argument.
 	// Note that this differs from FailedPrecondition. It indicates arguments
 	// that are problematic regardless of the state of the system
 	// (e.g., a malformed file name).
-	InvalidArgument ErrorCode = 2
+	InvalidArgument ErrorCode = 3
 
 	// DeadlineExceeded means operation expired before completion.
-	DeadlineExceeded ErrorCode = 3
+	// For operations that change the state of the system, this error may be
+	// returned even if the operation has completed successfully. For
+	// example, a successful response from a server could have been delayed
+	// long enough for the deadline to expire.
+	DeadlineExceeded ErrorCode = 4
 
 	// NotFound means some requested entity (e.g., file or directory) was
 	// not found.
-	NotFound ErrorCode = 4
+	NotFound ErrorCode = 5
 
 	// AlreadyExists means an attempt to create an entity failed because one
 	// already exists.
-	AlreadyExists ErrorCode = 5
+	AlreadyExists ErrorCode = 6
 
 	// PermissionDenied indicates the caller does not have permission to
 	// execute the specified operation. It must not be used for rejections
 	// caused by exhausting some resource (use ResourceExhausted
 	// instead for those errors). It must not be
 	// used if the caller cannot be identified (use Unauthenticated
 	// instead for those errors).
-	PermissionDenied ErrorCode = 6
+	PermissionDenied ErrorCode = 7
 
 	// ResourceExhausted indicates some resource has been exhausted, perhaps
 	// a per-user quota, or perhaps the entire file system is out of space.
-	ResourceExhausted ErrorCode = 7
+	ResourceExhausted ErrorCode = 8
 
 	// FailedPrecondition indicates operation was rejected because the
 	// system is not in a state required for the operation's execution.
@@ -65,15 +70,15 @@ const (
 	//      REST Get/Update/Delete on a resource and the resource on the
 	//      server does not match the condition. E.g., conflicting
 	//      read-modify-write on the same resource.
-	FailedPrecondition ErrorCode = 8
+	FailedPrecondition ErrorCode = 9
 
 	// Aborted indicates the operation was aborted, typically due to a
 	// concurrency issue like sequencer check failures, transaction aborts,
 	// etc.
 	//
 	// See litmus test above for deciding between FailedPrecondition,
 	// Aborted, and Unavailable.
-	Aborted ErrorCode = 9
+	Aborted ErrorCode = 10
 
 	// OutOfRange means operation was attempted past the valid range.
 	// E.g., seeking or reading past end of file.
@@ -90,24 +95,16 @@ const (
 	// error) when it applies so that callers who are iterating through
 	// a space can easily look for an OutOfRange error to detect when
 	// they are done.
-	//
-	// This error code will not be generated by the gRPC framework.
-	OutOfRange ErrorCode = 10
+	OutOfRange ErrorCode = 11
 
 	// Unimplemented indicates operation is not implemented or not
 	// supported/enabled in this service.
-	//
-	// This error code will be generated by the gRPC framework. Most
-	// commonly, you will see this error code when a method implementation
-	// is missing on the server. It can also be generated for unknown
-	// compression algorithms or a disagreement as to whether an RPC should
-	// be streaming.
-	Unimplemented ErrorCode = 11
+	Unimplemented ErrorCode = 12
 
 	// Internal errors. Means some invariants expected by underlying
 	// system has been broken. If you see one of these errors,
 	// something is very broken.
-	Internal ErrorCode = 12
+	Internal ErrorCode = 13
 
 	// Unavailable indicates the service is currently unavailable.
 	// This is a most likely a transient condition and may be corrected
@@ -116,17 +113,20 @@ const (
 	//
 	// See litmus test above for deciding between FailedPrecondition,
 	// Aborted, and Unavailable.
-	Unavailable ErrorCode = 13
+	Unavailable ErrorCode = 14
 
 	// DataLoss indicates unrecoverable data loss or corruption.
-	DataLoss ErrorCode = 14
+	DataLoss ErrorCode = 15
 
 	// Unauthenticated indicates the request does not have valid
 	// authentication credentials for the operation.
-	Unauthenticated ErrorCode = 15
+	Unauthenticated ErrorCode = 16
+
+	// Custom error codes not defined in the gRPC error space below here,
+	// starting at 100 to avoid collision with future gRPC defined codes.
 
 	// ConsensusFailed indicates failure to reach consensus
-	ConsensusFailed ErrorCode = 16
+	ConsensusFailed ErrorCode = 100
 )
 
 // String returns the string representation of the ErrorCode.
@@ -138,8 +138,8 @@ func (e ErrorCode) String() string {
 }
 
 var errorCodeToString = map[ErrorCode]string{
-	Uncategorized:      "Uncategorized",
-	Cancelled:          "Cancelled",
+	Canceled:           "Canceled",
+	Unknown:            "Unknown",
 	InvalidArgument:    "InvalidArgument",
 	DeadlineExceeded:   "DeadlineExceeded",
 	NotFound:           "NotFound",
@@ -157,11 +157,29 @@ var errorCodeToString = map[ErrorCode]string{
 	ConsensusFailed:    "ConsensusFailed",
 }
 
-// ErrorCodeFromInt returns the ErrorCode for a given int, or Uncategorized if not found.
-func ErrorCodeFromInt(i uint32) ErrorCode {
-	code := ErrorCode(i)
-	if _, ok := errorCodeToString[code]; ok {
+var stringToErrorCode = map[string]ErrorCode{
+	"Canceled":           Canceled,
+	"Unknown":            Unknown,
+	"InvalidArgument":    InvalidArgument,
+	"DeadlineExceeded":   DeadlineExceeded,
+	"NotFound":           NotFound,
+	"AlreadyExists":      AlreadyExists,
+	"PermissionDenied":   PermissionDenied,
+	"ResourceExhausted":  ResourceExhausted,
+	"FailedPrecondition": FailedPrecondition,
+	"Aborted":            Aborted,
+	"OutOfRange":         OutOfRange,
+	"Unimplemented":      Unimplemented,
+	"Internal":           Internal,
+	"Unavailable":        Unavailable,
+	"DataLoss":           DataLoss,
+	"Unauthenticated":    Unauthenticated,
+	"ConsensusFailed":    ConsensusFailed,
+}
+
+func FromErrorCodeString(str string) ErrorCode {
+	if code, ok := stringToErrorCode[str]; ok {
 		return code
 	}
-	return Uncategorized
+	return Unknown
 }