update capability error codes, API and finalize implementation

Author: ettec

pkg/capabilities/errors/error.go

@@ -0,0 +1,148 @@
+package errors
+
+import "fmt"
+
+type Origin int
+
+const (
+	// OriginSystem The error originated from a system issue.
+	OriginSystem = 0
+
+	// 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"
+	}
+}
+
+// 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
+
+	Visibility() Visibility
+	Origin() Origin
+	Code() ErrorCode
+	SerializeToString() string
+	SerializeToRemoteReportableString() string
+	Equals(otherErr Error) bool
+}
+
+type capabilityError struct {
+	err        error
+	origin     Origin
+	visibility Visibility
+	errorCode  ErrorCode
+}
+
+func NewError(err error, visibility Visibility, origin Origin, errorCode ErrorCode) Error {
+	return &capabilityError{
+		err:        err,
+		origin:     origin,
+		visibility: visibility,
+		errorCode:  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)
+}
+
+// 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)
+}
+
+// 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)
+}
+
+// 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) Origin() Origin {
+	return e.origin
+}
+
+func (e capabilityError) Visibility() Visibility {
+	return e.visibility
+}
+
+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

@@ -0,0 +1,185 @@
+package errors
+
+type ErrorCode uint32
+
+// Capability error codes are primarily based on gRPC error codes:
+// https://grpc.github.io/grpc/core/md_doc_statuscodes.html
+// Custom error codes specific to this project should start from 100 to avoid
+// conflicts with future gRPC codes. Note: 0 (OK) is intentionally excluded
+// because capability errors must always indicate a failure condition.
+const (
+	// Canceled indicates the operation was canceled (typically by the caller).
+	Canceled 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 = 3
+
+	// DeadlineExceeded means operation expired before completion.
+	// 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 = 5
+
+	// AlreadyExists means an attempt to create an entity failed because one
+	// already exists.
+	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 = 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 = 8
+
+	// FailedPrecondition indicates operation was rejected because the
+	// system is not in a state required for the operation's execution.
+	// For example, directory to be deleted may be non-empty, an rmdir
+	// operation is applied to a non-directory, etc.
+	//
+	// A litmus test that may help a service implementor in deciding
+	// between FailedPrecondition, Aborted, and Unavailable:
+	//  (a) Use Unavailable if the client can retry just the failing call.
+	//  (b) Use Aborted if the client should retry at a higher-level
+	//      (e.g., restarting a read-modify-write sequence).
+	//  (c) Use FailedPrecondition if the client should not retry until
+	//      the system state has been explicitly fixed. E.g., if an "rmdir"
+	//      fails because the directory is non-empty, FailedPrecondition
+	//      should be returned since the client should not retry unless
+	//      they have first fixed up the directory by deleting files from it.
+	//  (d) Use FailedPrecondition if the client performs conditional
+	//      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 = 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 = 10
+
+	// OutOfRange means operation was attempted past the valid range.
+	// E.g., seeking or reading past end of file.
+	//
+	// Unlike InvalidArgument, this error indicates a problem that may
+	// be fixed if the system state changes. For example, a 32-bit file
+	// system will generate InvalidArgument if asked to read at an
+	// offset that is not in the range [0,2^32-1], but it will generate
+	// OutOfRange if asked to read from an offset past the current
+	// file size.
+	//
+	// There is a fair bit of overlap between FailedPrecondition and
+	// OutOfRange. We recommend using OutOfRange (the more specific
+	// 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.
+	OutOfRange ErrorCode = 11
+
+	// Unimplemented indicates operation is not implemented or not
+	// supported/enabled in this service.
+	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 = 13
+
+	// Unavailable indicates the service is currently unavailable.
+	// This is a most likely a transient condition and may be corrected
+	// by retrying with a backoff. Note that it is not always safe to retry
+	// non-idempotent operations.
+	//
+	// See litmus test above for deciding between FailedPrecondition,
+	// Aborted, and Unavailable.
+	Unavailable ErrorCode = 14
+
+	// DataLoss indicates unrecoverable data loss or corruption.
+	DataLoss ErrorCode = 15
+
+	// Unauthenticated indicates the request does not have valid
+	// authentication credentials for the operation.
+	Unauthenticated ErrorCode = 16
+
+	// Custom error codes not defined in the gRPC error space are defined below this point,
+	// starting at 100 to avoid collision with future gRPC defined codes.
+
+	// ConsensusFailed indicates failure to reach consensus
+	ConsensusFailed ErrorCode = 100
+)
+
+// String returns the string representation of the ErrorCode.
+func (e ErrorCode) String() string {
+	if s, ok := errorCodeToString[e]; ok {
+		return s
+	}
+	return "Unknown"
+}
+
+var errorCodeToString = map[ErrorCode]string{
+	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",
+}
+
+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 Unknown
+}

pkg/capabilities/errors/error_serialization.go

@@ -0,0 +1,45 @@
+package errors
+
+import (
+	"errors"
+	"strings"
+)
+
+const errorMessageSeparator = ":"
+
+func PrePendPrivateVisibilityIdentifier(errorMessage string) string {
+	return Visibility(VisibilityPrivate).String() + errorMessageSeparator + errorMessage
+}
+
+func DeserializeErrorFromString(errorMsg string) Error {
+	parts := strings.SplitN(errorMsg, errorMessageSeparator, 4)
+
+	if len(parts) < 4 {
+		// To maintain backwards compatability with messages from remote nodes on an older code version, create an error
+		// with the full message and default to private system error with an unknown error code.
+		return NewError(errors.New(errorMsg), Visibility(VisibilityPrivate), Origin(OriginSystem), Unknown)
+	}
+
+	visibility := FromVisibilityString(parts[0])
+	origin := FromOriginString(parts[1])
+	errorCode := FromErrorCodeString(parts[2])
+	errorMsg = parts[3]
+
+	return NewError(errors.New(errorMsg), visibility, origin, errorCode)
+}
+
+func (e capabilityError) SerializeToString() string {
+	return e.serializeToString(e.err.Error())
+}
+
+func (e capabilityError) serializeToString(errMsg string) string {
+	return e.visibility.String() + errorMessageSeparator + e.origin.String() + errorMessageSeparator + e.Code().String() + errorMessageSeparator + errMsg
+}
+
+func (e capabilityError) SerializeToRemoteReportableString() string {
+	if e.Visibility() == VisibilityPublic {
+		return e.serializeToString(e.err.Error())
+	}
+
+	return e.serializeToString(": error whilst executing capability - the error message is not publicly reportable")
+}