errors

Documentation

Index

• Variables
• func As(err error, target interface{}) bool
• func E(opt ...Option) error
• func Is(err, target error) bool
• func IsCheckConstraintError(err error) bool
• func IsMissingTableError(err error) bool
• func IsNotFoundError(err error) bool
• func IsNotNullError(err error) bool
• func IsUniqueError(err error) bool
• func Match(t *Template, err error) bool
• func New(c Code, op Op, msg string, opt ...Option) error
• func Wrap(e error, op Op, opt ...Option) error
• type Code
  • func (c Code) Info() Info
  • func (c Code) String() string
• type Err
  • func Convert(e error) *Err
  • func (e *Err) Error() string
  • func (e *Err) Info() Info
  • func (e *Err) Unwrap() error
• type Info
• type Kind
  • func (e Kind) String() string
• type Op
• type Option
  • func WithCode(code Code) Option
  • func WithMsg(msg string) Option
  • func WithOp(op Op) Option
  • func WithWrap(e error) Option
• type Options
  • func GetOpts(opt ...Option) Options
• type Template
  • func T(args ...interface{}) *Template
  • func (t *Template) Error() string
  • func (t *Template) Info() Info

Variables

var (
	// ErrInvalidPublicId indicates an invalid PublicId.
	ErrInvalidPublicId = E(WithCode(InvalidParameter), WithMsg("invalid publicId"))

	// ErrInvalidParameter is returned by create and update methods if
	// an attribute on a struct contains illegal or invalid values.
	ErrInvalidParameter = E(WithCode(InvalidParameter), WithMsg("invalid parameter"))

	// ErrInvalidFieldMask is returned by update methods if the field mask
	// contains unknown fields or fields that cannot be updated.
	ErrInvalidFieldMask = E(WithCode(InvalidFieldMask), WithMsg("invalid field mask"))

	// ErrEmptyFieldMask is returned by update methods if the field mask is
	// empty.
	ErrEmptyFieldMask = E(WithCode(EmptyFieldMask), WithMsg("empty field mask"))

	// ErrNotUnique is returned by create and update methods when a write
	// to the repository resulted in a unique constraint violation.
	ErrNotUnique = E(WithCode(NotUnique), WithMsg("unique constraint violation"))

	// ErrNotNull is returned by methods when a write to the repository resulted
	// in a check constraint violation
	ErrCheckConstraint = E(WithCode(CheckConstraint), WithMsg("check constraint violated"))

	// ErrNotNull is returned by methods when a write to the repository resulted
	// in a not null constraint violation
	ErrNotNull = E(WithCode(NotNull), WithMsg("not null constraint violated"))

	// ErrRecordNotFound returns a "record not found" error and it only occurs
	// when attempting to read from the database into struct.
	// When reading into a slice it won't return this error.
	ErrRecordNotFound = E(WithCode(RecordNotFound), WithMsg("record not found"))

	// ErrMultipleRecords is returned by update and delete methods when a
	// write to the repository would result in more than one record being
	// changed resulting in the transaction being rolled back.
	ErrMultipleRecords = E(WithCode(MultipleRecords), WithMsg("multiple records"))
)

Errors returned from this package may be tested against these errors with errors.Is. Creating new Sentinel type errors like these should be deprecated in favor of the new Err type that includes unique Codes and a Matching function.

Functions

func As

func As(err error, target interface{}) bool

As is the equivalent of the std errors.As, and allows devs to only import this package for the capability.

func E

func E(opt ...Option) error

E creates a new Err with provided code and supports the options of:

* WithOp() - allows you to specify an optional Op (operation).

* WithMsg() - allows you to specify an optional error msg, if the default msg for the error Code is not sufficient.

* WithWrap() - allows you to specify an error to wrap. If the wrapped error is a boundary domain error, the wrapped error code will be used as the returned error's code.

* WithCode() - allows you to specify an optional Code, this code will be prioritized over a code used from WithWrap().

func Is

func Is(err, target error) bool

Is the equivalent of the std errors.Is, but allows Devs to only import this package for the capability.

func IsCheckConstraintError

func IsCheckConstraintError(err error) bool

IsCheckConstraintError returns a boolean indicating whether the error is known to report a check constraint violation.

func IsMissingTableError

func IsMissingTableError(err error) bool

IsMissingTableError returns a boolean indicating whether the error is known to report a undefined/missing table violation.

func IsNotFoundError

func IsNotFoundError(err error) bool

IsNotFoundError returns a boolean indicating whether the error is known to report a not found violation.

func IsNotNullError

func IsNotNullError(err error) bool

IsNotNullError returns a boolean indicating whether the error is known to report a not-null constraint violation.

func IsUniqueError

func IsUniqueError(err error) bool

IsUniqueError returns a boolean indicating whether the error is known to report a unique constraint violation.

func Match

func Match(t *Template, err error) bool

Match the template against the error. The error must be of type *Err, or wrap an error of type *Err, otherwise match will return false. Matches all non-empty fields of the template against the error.

func New

func New(c Code, op Op, msg string, opt ...Option) error

New creates a new Err with provided code, op and msg It supports the options of:

* WithWrap() - allows you to specify an error to wrap

func Wrap

func Wrap(e error, op Op, opt ...Option) error

Wrap creates a new Err from the provided err and op, preserving the code from the originating error. It supports the options of:

* WithMsg() - allows you to specify an optional error msg, if the default msg for the error Code is not sufficient.

Types

type Code

type Code uint32

Code specifies a code for the error.

const (
	Unknown Code = 0 // Unknown will be equal to a zero value for Codes

	// General function errors are reserved Codes 100-999
	InvalidParameter Code = 100 // InvalidParameter represents an invalid parameter for an operation.
	InvalidAddress   Code = 101 // InvalidAddress represents an invalid host address for an operation
	InvalidPublicId  Code = 102 // InvalidPublicId represents an invalid public Id for an operation
	InvalidFieldMask Code = 103 // InvalidFieldMask represents an invalid field mast for an operation
	EmptyFieldMask   Code = 104 // EmptyFieldMask represents an empty field mask for an operation

	// PasswordTooShort results from attempting to set a password which is to short.
	PasswordTooShort Code = 200

	// PasswordUnsupportedConfiguration results from attempting to perform an
	// operation that sets a password configuration to an unsupported type.
	PasswordUnsupportedConfiguration Code = 201

	// PasswordInvalidConfiguration results from attempting to perform an
	// operation that sets a valid password configuration with invalid settings.
	PasswordInvalidConfiguration Code = 202

	// PasswordsEqual is returned from ChangePassword when the old and
	// new passwords are equal.
	PasswordsEqual Code = 203

	// DB errors are reserved Codes from 1000-1999
	CheckConstraint      Code = 1000 // CheckConstraint represents a check constraint error
	NotNull              Code = 1001 // NotNull represents a value must not be null error
	NotUnique            Code = 1002 // NotUnique represents a value must be unique error
	NotSpecificIntegrity Code = 1003 // NotSpecificIntegrity represents an integrity error that has no specific domain error code
	MissingTable         Code = 1004 // Missing table represents an undefined table error
	RecordNotFound       Code = 1100 // RecordNotFound represents that a record/row was not found matching the criteria
	MultipleRecords      Code = 1101 // MultipleRecords represents that multiple records/rows were found matching the criteria
	ColumnNotFound       Code = 1102 // ColumnNotFound represent that a column was not found in the underlying db
	MaxRetries           Code = 1103 // MaxRetries represent that a db Tx hit max retires allowed
	Exception            Code = 1104 // Exception represent that an underlying db exception was raised
)

func (Code) Info

func (c Code) Info() Info

Info will look up the Code's Info. If the Info is not found, it will return Info for an Unknown Code.

func (Code) String

func (c Code) String() string

String will return the Code's Info.Message

type Err

type Err struct {
	// Code is the error's code, which can be used to get the error's
	// errorCodeInfo, which contains the error's Kind and Message
	Code Code

	// Msg for the error
	Msg string

	// Op represents the operation raising/propagating an error and is optional
	Op Op

	// Wrapped is the error which this Err wraps and will be nil if there's no
	// error to wrap.
	Wrapped error
}

Err provides the ability to specify a Msg, Op, Code and Wrapped error. We've chosen Err over Error for the identifier to support the easy embedding of Errs. Errs can be embedded without a conflict between the embedded Err and Err.Error().

func Convert

func Convert(e error) *Err

Convert will convert the error to a Boundary *Err (returning it as an error) and attempt to add a helpful error msg as well. If that's not possible, it will return nil

func (*Err) Error

func (e *Err) Error() string

Error satisfies the error interface and returns a string representation of the Err

func (*Err) Info

func (e *Err) Info() Info

Info about the Err

func (*Err) Unwrap

func (e *Err) Unwrap() error

Unwrap implements the errors.Unwrap interface and allows callers to use the errors.Is() and errors.As() functions effectively for any wrapped errors.

type Info

type Info struct {
	// Kind specifies the kind of error (unknown, parameter, integrity, etc).
	Kind Kind

	// Message provides a default message for the error code
	Message string
}

Info contains details of the specific error code

type Kind

type Kind uint32

Kind specifies the kind of error (unknown, parameter, integrity, etc).

const (
	Other Kind = iota
	Parameter
	Integrity
	Search
	Password
	Transaction
)

func (Kind) String

func (e Kind) String() string

type Op

type Op string

Op represents an operation (package.function). For example iam.CreateRole

type Option

type Option func(*Options)

Option - how Options are passed as arguments.

func WithCode

func WithCode(code Code) Option

WithCode provides an option to provide a code when creating a new error.

func WithMsg

func WithMsg(msg string) Option

WithMsg provides an option to provide a message when creating a new error.

func WithOp

func WithOp(op Op) Option

WithOp provides an option to provide the operation that's raising/propagating the error.

func WithWrap

func WithWrap(e error) Option

WithErrCode provides an option to provide an error to wrap when creating a new error.

type Options

type Options struct {
	// contains filtered or unexported fields
}

Options - how Options are represented.

func GetOpts

func GetOpts(opt ...Option) Options

GetOpts - iterate the inbound Options and return a struct.

type Template

type Template struct {
	Err       // Err embedded to support matching Errs
	Kind Kind // Kind allows explicit matching on a Template without a Code.
}

Template is useful constructing Match Err templates. Templates allow you to match Errs without specifying a Code. In other words, just Match using the Errs: Kind, Op, etc.

func T

func T(args ...interface{}) *Template

T creates a new Template for matching Errs. Invalid parameters are ignored. If more than is one parameter for a given type, only the last one is used.

func (*Template) Error

func (t *Template) Error() string

Error satisfies the error interface but we intentionally don't return anything of value, in an effort to stop users from substituting Templates in place of Errs, when creating domain errors.

func (*Template) Info

func (t *Template) Info() Info

Info about the Template, which is useful when matching a Template's Kind with an Err's Kind.