errors

Documentation

Index

• Variables
• func HandleAPIError(ctx iris.Context, err error)
• func RegisterErrorCode(canonicalName ErrorCodeName, httpStatusCode int)
• func RegisterErrorCodeMap(errorMap map[ErrorCodeName]int)
• type Error
  • func (err Error) Error() string
• type ErrorCode
• type ErrorCodeName
  • func E(httpErrorCanonicalName string, httpStatusCode int) ErrorCodeName
  • func (e ErrorCodeName) Data(ctx iris.Context, msg string, data interface{})
  • func (e ErrorCodeName) DataWithDetails(ctx iris.Context, msg, details string, data interface{})
  • func (e ErrorCodeName) Details(ctx iris.Context, msg, details string, detailsArgs ...interface{})
  • func (e ErrorCodeName) Err(ctx iris.Context, err error)
  • func (e ErrorCodeName) Log(ctx iris.Context, format string, args ...interface{})
  • func (e ErrorCodeName) LogErr(ctx iris.Context, err error)
  • func (e ErrorCodeName) Message(ctx iris.Context, format string, args ...interface{})
  • func (e ErrorCodeName) Validation(ctx iris.Context, errs ...ValidationError)
• type LogErrorFunc
• type ValidationError
  • func (e ValidationError) Error() string
• type ValidationErrors
  • func AsValidationErrors(err error) (ValidationErrors, bool)
  • func (e *ValidationErrors) Add(err ValidationError) *ValidationErrors
  • func (e ValidationErrors) Error() string
  • func (e ValidationErrors) Is(err error) bool
  • func (e *ValidationErrors) Join(errs ValidationErrors) *ValidationErrors
  • func (e *ValidationErrors) MustBeInRangeString(field string, value string, minIncluding, maxIncluding int) bool
  • func (e *ValidationErrors) MustBeNotEmptyString(field string, value string) bool
  • func (e *ValidationErrors) MustBeSatisfied(field string, value string, regex *regexp.Regexp) bool
  • func (e *ValidationErrors) MustBeSatisfiedFunc(field string, value string, isEqualFunc func(string) bool) bool
  • func (e *ValidationErrors) Validate(field string, value interface{}) bool
• type ValueValidator

Variables

var (
	// Is is an alias of the standard errors.Is function.
	Is = errors.Is
	// As is an alias of the standard errors.As function.
	As = errors.As
	// New is an alias of the standard errors.New function.
	New = errors.New
	// Unwrap is an alias of the standard errors.Unwrap function.
	Unwrap = errors.Unwrap
)

var (
	// ErrUnexpected is the HTTP error which sent to the client
	// when server fails to send an error, it's a fallback error.
	// The server fails to send an error on two cases:
	// 1. when the provided error code name is not registered (the error value is the ErrUnexpectedErrorCode)
	// 2. when the error contains data but cannot be encoded to json (the value of the error is the result error of json.Marshal).
	ErrUnexpected = E("UNEXPECTED_ERROR", iris.StatusInternalServerError)
	// ErrUnexpectedErrorCode is the error which logged
	// when the given error code name is not registered.
	ErrUnexpectedErrorCode = New("unexpected error code name")
)

var SkipCanceled = true

SkipCanceled is a package-level setting which by default skips the logging of a canceled response or operation. See the "Context.IsCanceled()" method and "iris.IsCanceled()" function that decide if the error is caused by a canceled operation.

Change of this setting MUST be done on initialization of the program.

Functions

func HandleAPIError

func HandleAPIError(ctx iris.Context, err error)

HandleAPIError handles remote server errors. Optionally, use it when you write your server's HTTP clients using the the /x/client package. When the HTTP Client sends data to a remote server but that remote server failed to accept the request as expected, then the error will be proxied to this server's end-client.

When the given "err" is not a type of client.APIError then the error will be sent using the "Internal.LogErr" method which sends HTTP internal server error to the end-client and prints the "err" using the "LogError" package-level function.

func RegisterErrorCode

func RegisterErrorCode(canonicalName ErrorCodeName, httpStatusCode int)

RegisterErrorCode registers a custom HTTP Error.

This method MUST be called on initialization, before HTTP server starts as the internal map is not protected by mutex.

func RegisterErrorCodeMap

func RegisterErrorCodeMap(errorMap map[ErrorCodeName]int)

RegisterErrorCodeMap registers one or more custom HTTP Errors.

This method MUST be called on initialization, before HTTP server starts as the internal map is not protected by mutex.

Types

type Error

type Error struct {
	ErrorCode        ErrorCode        `json:"http_error_code" yaml:"HTTPErrorCode"`
	Message          string           `json:"message,omitempty" yaml:"Message"`
	Details          string           `json:"details,omitempty" yaml:"Details"`
	ValidationErrors ValidationErrors `json:"validation,omitempty" yaml:"Validation,omitempty"`
	Data             json.RawMessage  `json:"data,omitempty" yaml:"Data,omitempty"` // any other custom json data.
}

Error represents the JSON form of "http wire errors".

func (Error) Error

func (err Error) Error() string

Error method completes the error interface. It just returns the canonical name, status code, message and details.

type ErrorCode

type ErrorCode struct {
	CanonicalName ErrorCodeName `json:"canonical_name" yaml:"CanonicalName"`
	Status        int           `json:"status" yaml:"Status"`
}

ErrorCode represents the JSON form ErrorCode of the Error.

type ErrorCodeName

type ErrorCodeName string

ErrorCodeName is a custom string type represents canonical error names.

It contains functionality for safe and easy error populating. See its "Message", "Details", "Data" and "Log" methods.

var (
	Cancelled          ErrorCodeName = E("CANCELLED", iris.StatusTokenRequired)
	Unknown            ErrorCodeName = E("UNKNOWN", iris.StatusInternalServerError)
	InvalidArgument    ErrorCodeName = E("INVALID_ARGUMENT", iris.StatusBadRequest)
	DeadlineExceeded   ErrorCodeName = E("DEADLINE_EXCEEDED", iris.StatusGatewayTimeout)
	NotFound           ErrorCodeName = E("NOT_FOUND", iris.StatusNotFound)
	AlreadyExists      ErrorCodeName = E("ALREADY_EXISTS", iris.StatusConflict)
	PermissionDenied   ErrorCodeName = E("PERMISSION_DENIED", iris.StatusForbidden)
	Unauthenticated    ErrorCodeName = E("UNAUTHENTICATED", iris.StatusUnauthorized)
	ResourceExhausted  ErrorCodeName = E("RESOURCE_EXHAUSTED", iris.StatusTooManyRequests)
	FailedPrecondition ErrorCodeName = E("FAILED_PRECONDITION", iris.StatusBadRequest)
	Aborted            ErrorCodeName = E("ABORTED", iris.StatusConflict)
	OutOfRange         ErrorCodeName = E("OUT_OF_RANGE", iris.StatusBadRequest)
	Unimplemented      ErrorCodeName = E("UNIMPLEMENTED", iris.StatusNotImplemented)
	Internal           ErrorCodeName = E("INTERNAL", iris.StatusInternalServerError)
	Unavailable        ErrorCodeName = E("UNAVAILABLE", iris.StatusServiceUnavailable)
	DataLoss           ErrorCodeName = E("DATA_LOSS", iris.StatusInternalServerError)
)

List of default error codes a server should follow and send back to the client.

func E

func E(httpErrorCanonicalName string, httpStatusCode int) ErrorCodeName

E registers a custom HTTP Error and returns its canonical name for future use. The method "New" is reserved and was kept as it is for compatibility with the standard errors package, therefore the "E" name was chosen instead. The key stroke "e" is near and accessible while typing the "errors" word so developers may find it easy to use.

See "RegisterErrorCode" and "RegisterErrorCodeMap" for alternatives.

Example:

	var (
   NotFound = errors.E("NOT_FOUND", iris.StatusNotFound)
	)
	...
	NotFound.Details(ctx, "resource not found", "user with id: %q was not found", userID)

This method MUST be called on initialization, before HTTP server starts as the internal map is not protected by mutex.

func (ErrorCodeName) Data

func (e ErrorCodeName) Data(ctx iris.Context, msg string, data interface{})

Data sends an error with a message and json data to the client.

func (ErrorCodeName) DataWithDetails

func (e ErrorCodeName) DataWithDetails(ctx iris.Context, msg, details string, data interface{})

DataWithDetails sends an error with a message, details and json data to the client.

func (ErrorCodeName) Details

func (e ErrorCodeName) Details(ctx iris.Context, msg, details string, detailsArgs ...interface{})

Details sends an error with a message and details to the client.

func (ErrorCodeName) Err

func (e ErrorCodeName) Err(ctx iris.Context, err error)

Err sends the error's text as a message to the client. In exception, if the given "err" is a type of validation error then the Validation method is called instead.

func (ErrorCodeName) Log

func (e ErrorCodeName) Log(ctx iris.Context, format string, args ...interface{})

Log sends an error of "format" and optional "args" to the client and prints that error using the "LogError" package-level function, which can be customized.

See "LogErr" too.

func (ErrorCodeName) LogErr

func (e ErrorCodeName) LogErr(ctx iris.Context, err error)

LogErr sends the given "err" as message to the client and prints that error to using the "LogError" package-level function, which can be customized.

func (ErrorCodeName) Message

func (e ErrorCodeName) Message(ctx iris.Context, format string, args ...interface{})

Message sends an error with a simple message to the client.

func (ErrorCodeName) Validation

func (e ErrorCodeName) Validation(ctx iris.Context, errs ...ValidationError)

Validation sends an error which contains the invalid fields to the client.

type LogErrorFunc

type LogErrorFunc = func(ctx iris.Context, err error)

LogErrorFunc is an alias of a function type which accepts the Iris request context and an error and it's fired whenever an error should be logged.

See "OnErrorLog" variable to change the way an error is logged, by default the error is logged using the Application's Logger's Error method.

var LogError LogErrorFunc = func(ctx iris.Context, err error) {
	ctx.Application().Logger().Error(err)
}

LogError can be modified to customize the way an error is logged to the server (most common: internal server errors, database errors et.c.). Can be used to customize the error logging, e.g. using Sentry (cloud-based error console).

type ValidationError

type ValidationError struct {
	Field  string      `json:"field" yaml:"Field"`
	Value  interface{} `json:"value" yaml:"Value"`
	Reason string      `json:"reason" yaml:"Reason"`
}

ValidationError describes a field validation error.

func (ValidationError) Error

func (e ValidationError) Error() string

Error completes the standard error interface.

type ValidationErrors

type ValidationErrors []ValidationError

ValidationErrors is just a custom type of ValidationError slice.

func AsValidationErrors

func AsValidationErrors(err error) (ValidationErrors, bool)

AsValidationErrors reports wheether the given "err" is a type of validation error(s).

func (*ValidationErrors) Add

func (e *ValidationErrors) Add(err ValidationError) *ValidationErrors

Add is a helper for appending a validation error.

func (ValidationErrors) Error

func (e ValidationErrors) Error() string

Error completes the error interface.

func (ValidationErrors) Is

func (e ValidationErrors) Is(err error) bool

Is reports whether the given "err" is a type of validation error or validation errors.

func (*ValidationErrors) Join

func (e *ValidationErrors) Join(errs ValidationErrors) *ValidationErrors

Join joins an existing Errors to this errors list.

func (*ValidationErrors) MustBeInRangeString

func (e *ValidationErrors) MustBeInRangeString(field string, value string, minIncluding, maxIncluding int) bool

MustBeInRangeString reports whether the "value" is in range of min and max.

func (*ValidationErrors) MustBeNotEmptyString

func (e *ValidationErrors) MustBeNotEmptyString(field string, value string) bool

MustBeNotEmptyString reports and fails if the given "value" is empty.

func (*ValidationErrors) MustBeSatisfied

func (e *ValidationErrors) MustBeSatisfied(field string, value string, regex *regexp.Regexp) bool

MustBeSatisfied compares the value with the given regex and reports if it's valid or not. If it's not valid, a new ValidationError is added to the "e" list.

func (*ValidationErrors) MustBeSatisfiedFunc

func (e *ValidationErrors) MustBeSatisfiedFunc(field string, value string, isEqualFunc func(string) bool) bool

MustBeSatisfiedFunc compares the value with the given "isEqualFunc" function and reports if it's valid or not. If it's not valid, a new ValidationError is added to the "e" list.

func (*ValidationErrors) Validate

func (e *ValidationErrors) Validate(field string, value interface{}) bool

Validate returns the result of the value's Validate method, if exists otherwise it adds the field and value to the error list and reports false (invalidated). If reason is empty, means that the field is valid, this method will return true.

type ValueValidator

type ValueValidator interface {
	Validate() string
}

ValueValidator is a generic interface which can be used to check if the value is valid for insert (or for comparison inside another validation step). Useful for enums. Should return a non-empty string on validation error, that string is the failure reason.