errs

Documentation

Overview

Package errs provides errors for both APIs and CLIs.

This package is primarily meant to provde a transport-agnostic abstraction of errors that can be easily mapped to both Twirp and gRPC.

Errors in this package are not meant to be sent across the wire, so there is no parsing functionality. Rely on the transport-specific mechanism for over-the-wire operations.

Index

• func Append(one error, two error) error
• func IsError(err error) bool
• func NewAborted(message string) error
• func NewAbortedf(format string, args ...interface{}) error
• func NewAlreadyExists(message string) error
• func NewAlreadyExistsf(format string, args ...interface{}) error
• func NewCanceled(message string) error
• func NewCanceledf(format string, args ...interface{}) error
• func NewDataLoss(message string) error
• func NewDataLossf(format string, args ...interface{}) error
• func NewDeadlineExceeded(message string) error
• func NewDeadlineExceededf(format string, args ...interface{}) error
• func NewError(code Code, message string) error
• func NewErrorf(code Code, format string, args ...interface{}) error
• func NewFailedPrecondition(message string) error
• func NewFailedPreconditionf(format string, args ...interface{}) error
• func NewInternal(message string) error
• func NewInternalf(format string, args ...interface{}) error
• func NewInvalidArgument(message string) error
• func NewInvalidArgumentf(format string, args ...interface{}) error
• func NewNotFound(message string) error
• func NewNotFoundf(format string, args ...interface{}) error
• func NewOutOfRange(message string) error
• func NewOutOfRangef(format string, args ...interface{}) error
• func NewPermissionDenied(message string) error
• func NewPermissionDeniedf(format string, args ...interface{}) error
• func NewResourceExhausted(message string) error
• func NewResourceExhaustedf(format string, args ...interface{}) error
• func NewUnauthenticated(message string) error
• func NewUnauthenticatedf(format string, args ...interface{}) error
• func NewUnavailable(message string) error
• func NewUnavailablef(format string, args ...interface{}) error
• func NewUnimplemented(message string) error
• func NewUnimplementedf(format string, args ...interface{}) error
• func NewUnknown(message string) error
• func NewUnknownf(format string, args ...interface{}) error
• type Code
  • func GetCode(err error) Code
  • func (c Code) String() string

Functions

func Append

func Append(one error, two error) error

Append combines the two errors.

If both are nil, this returns nil. If one is nil, this returns two. If two is nil, this returns one.

If both are non-nil this will convert both to errors for this package. The error messages will be concatanated, and the Code will be one of the following:

If both codes are equal, this returns an error with that Code. If the codes are unequal, this returns an error with CodeInternal.

func IsError

func IsError(err error) bool

IsError returns true if err is an error created by this package.

Returns false if err == nil.nil

func NewAborted

func NewAborted(message string) error

NewAborted is a convenience function for errors with CodeAborted.

func NewAbortedf

func NewAbortedf(format string, args ...interface{}) error

NewAbortedf is a convenience function for errors with CodeAborted.

func NewAlreadyExists

func NewAlreadyExists(message string) error

NewAlreadyExists is a convenience function for errors with CodeAlreadyExists.

func NewAlreadyExistsf

func NewAlreadyExistsf(format string, args ...interface{}) error

NewAlreadyExistsf is a convenience function for errors with CodeAlreadyExists.

func NewCanceled

func NewCanceled(message string) error

NewCanceled is a convenience function for errors with CodeCanceled.

func NewCanceledf

func NewCanceledf(format string, args ...interface{}) error

NewCanceledf is a convenience function for errors with CodeCanceled.

func NewDataLoss

func NewDataLoss(message string) error

NewDataLoss is a convenience function for errors with CodeDataLoss.

func NewDataLossf

func NewDataLossf(format string, args ...interface{}) error

NewDataLossf is a convenience function for errors with CodeDataLoss.

func NewDeadlineExceeded

func NewDeadlineExceeded(message string) error

NewDeadlineExceeded is a convenience function for errors with CodeDeadlineExceeded.

func NewDeadlineExceededf

func NewDeadlineExceededf(format string, args ...interface{}) error

NewDeadlineExceededf is a convenience function for errors with CodeDeadlineExceeded.

func NewError

func NewError(code Code, message string) error

NewError returns a new error with a code.

The value of Error() will only contain the message. If you would like to also print the code, you must do this manually.

If the code is invalid, an error with CodeInternal will be returned.

func NewErrorf

func NewErrorf(code Code, format string, args ...interface{}) error

NewErrorf returns a new error.

The value of Error() will only contain the message. If you would like to also print the code, you must do this manually.

If the code is invalid, an error with CodeInternal will be returned.

func NewFailedPrecondition

func NewFailedPrecondition(message string) error

NewFailedPrecondition is a convenience function for errors with CodeFailedPrecondition.

func NewFailedPreconditionf

func NewFailedPreconditionf(format string, args ...interface{}) error

NewFailedPreconditionf is a convenience function for errors with CodeFailedPrecondition.

func NewInternal

func NewInternal(message string) error

NewInternal is a convenience function for errors with CodeInternal.

func NewInternalf

func NewInternalf(format string, args ...interface{}) error

NewInternalf is a convenience function for errors with CodeInternal.

func NewInvalidArgument

func NewInvalidArgument(message string) error

NewInvalidArgument is a convenience function for errors with CodeInvalidArgument.

func NewInvalidArgumentf

func NewInvalidArgumentf(format string, args ...interface{}) error

NewInvalidArgumentf is a convenience function for errors with CodeInvalidArgument.

func NewNotFound

func NewNotFound(message string) error

NewNotFound is a convenience function for errors with CodeNotFound.

func NewNotFoundf

func NewNotFoundf(format string, args ...interface{}) error

NewNotFoundf is a convenience function for errors with CodeNotFound.

func NewOutOfRange

func NewOutOfRange(message string) error

NewOutOfRange is a convenience function for errors with CodeOutOfRange.

func NewOutOfRangef

func NewOutOfRangef(format string, args ...interface{}) error

NewOutOfRangef is a convenience function for errors with CodeOutOfRange.

func NewPermissionDenied

func NewPermissionDenied(message string) error

NewPermissionDenied is a convenience function for errors with CodePermissionDenied.

func NewPermissionDeniedf

func NewPermissionDeniedf(format string, args ...interface{}) error

NewPermissionDeniedf is a convenience function for errors with CodePermissionDenied.

func NewResourceExhausted

func NewResourceExhausted(message string) error

NewResourceExhausted is a convenience function for errors with CodeResourceExhausted.

func NewResourceExhaustedf

func NewResourceExhaustedf(format string, args ...interface{}) error

NewResourceExhaustedf is a convenience function for errors with CodeResourceExhausted.

func NewUnauthenticated

func NewUnauthenticated(message string) error

NewUnauthenticated is a convenience function for errors with CodeUnauthenticated.

func NewUnauthenticatedf

func NewUnauthenticatedf(format string, args ...interface{}) error

NewUnauthenticatedf is a convenience function for errors with CodeUnauthenticated.

func NewUnavailable

func NewUnavailable(message string) error

NewUnavailable is a convenience function for errors with CodeUnavailable.

func NewUnavailablef

func NewUnavailablef(format string, args ...interface{}) error

NewUnavailablef is a convenience function for errors with CodeUnavailable.

func NewUnimplemented

func NewUnimplemented(message string) error

NewUnimplemented is a convenience function for errors with CodeUnimplemented.

func NewUnimplementedf

func NewUnimplementedf(format string, args ...interface{}) error

NewUnimplementedf is a convenience function for errors with CodeUnimplemented.

func NewUnknown

func NewUnknown(message string) error

NewUnknown is a convenience function for errors with CodeUnknown.

func NewUnknownf

func NewUnknownf(format string, args ...interface{}) error

NewUnknownf is a convenience function for errors with CodeUnknown.

Types

type Code

type Code int

Code is an error code.

Unlike gRPC and Twirp, there is no zero code for success.

All errors must have a valid code. If an error does not have a valid code when performing error operations, a new error with CodeInternal will be returned.

const (
	// CodeOK is a sentinel code for no error.
	//
	// No error should use this directly. This is returned by GetCode if the error is nil.
	CodeOK Code = 0

	// CodeCanceled indicates the operation was canceled.
	//
	// HTTP equivalent: 408 REQUEST TIMEOUT
	CodeCanceled Code = 1

	// CodeUnknown indicates an unknown error.
	//
	// This is for errors that do not have specific error information.
	//
	// HTTP equivalent: 500 INTERNAL SERVER ERROR
	CodeUnknown Code = 2

	// CodeInvalidArgument indicates that the an invalid argument was specified, for
	// example missing required arguments and invalid arguments.
	//
	// HTTP equivalent: 400 BAD REQUEST
	CodeInvalidArgument Code = 3

	// CodeDeadlineExceeded indicates that a deadline was exceeded, for example a timeout.
	//
	// HTTP equivalent: 504 GATEWAY TIMEOUT
	// Note that Twirp treats this as a 408 REQUEST TIMEOUT, but grpc-gateway treats this
	// as 504 GATEWAY TIMEOUT.
	CodeDeadlineExceeded Code = 4

	// CodeNotFound indicates that an entity was not found.
	//
	// HTTP equivalent: 404 NOT FOUND
	CodeNotFound Code = 5

	// CodeAlreadyExists indicates that entity creation was unsuccesful as the entity
	// already exists.
	//
	// HTTP equivalent: 409 CONFLICT
	CodeAlreadyExists Code = 6

	// CodePermissionDenied indicates the caller does not have permission to perform
	// the requested operation.
	//
	// HTTP equivalent: 403 FORBIDDEN
	CodePermissionDenied Code = 7

	// CodeResourceExhausted indicates some resource has been exhausted, for example
	// throttling or out-of-space errors.
	//
	// HTTP equivalent: 429 TOO MANY REQUESTS
	// Note that Twirp treats this as 403 FORBIDDEN, but grpc-gateway treats this
	// as 429 TOO MANY REQUESTS.
	CodeResourceExhausted Code = 8

	// CodeFailedPrecondition indicates operation was rejected because the system is not
	// in a state required for the operation's execution, for example a non-recursive
	// non-empty directory deletion.
	//
	// HTTP equivalent: 400 BAD REQUEST
	// Note that Twirp treats this as 412 PRECONDITION FAILED, but grpc-gateway treats this
	// as 400 BAD REQUEST, and has a note saying this is on purpose (and it makes sense).
	CodeFailedPrecondition Code = 9

	// CodeAborted indicates the operation was aborted, for example when a transaction
	// is aborted.
	//
	// HTTP equivalent: 409 CONFLICT
	CodeAborted Code = 10

	// CodeOutOfRange indicates an operation was attempted past the valid range, for example
	// seeking or reading past the end of a paginated collection.
	//
	// Unlike InvalidArgument, this error indicates a problem that may be fixed if
	// the system state changes (i.e. adding more items to the collection).
	//
	// 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.
	//
	// HTTP equivant: 400 BAD REQUEST
	CodeOutOfRange Code = 11

	// CodeUnimplemented indicates operation is not implemented or not
	// supported/enabled in this service.
	//
	// HTTP equivalent: 501 NOT IMPLEMENTED
	CodeUnimplemented Code = 12

	// CodeInternal indicates an internal system error.
	//
	// HTTP equivalent: 500 INTERNAL SERVER ERROR
	CodeInternal Code = 13

	// CodeUnavailable indicates the service is currently unavailable.
	// This is a most likely a transient condition and may be corrected
	// by retrying with a backoff.
	//
	// HTTP equivalent: 503 SERVICE UNAVAILABLE
	CodeUnavailable Code = 14

	// CodeDataLoss indicates unrecoverable data loss or corruption.
	//
	// HTTP equivalent: 500 INTERNAL SERVER ERROR
	CodeDataLoss Code = 15

	// CodeUnauthenticated indicates the request does not have valid
	// authentication credentials for the operation. This is different than
	// PermissionDenied, which deals with authorization.
	//
	// HTTP equivalent: 401 UNAUTHORIZED
	CodeUnauthenticated Code = 16
)

func GetCode

func GetCode(err error) Code

GetCode gets the error code.

If the error is nil, this returns CodeOK. If the error is not created by this package, it will return CodeInternal.

Note that gRPC maps to CodeUnknown in the same scenario.

func (Code) String

func (c Code) String() string

String returns the string value of c.